Seatsurfing 1.136 配置参数详解

目标：把 Seatsurfing 1.136.3 的全部配置项一次讲透——部署级环境变量（官方全表 35+ 项）与组织级业务设置（管理后台/设置接口实测 49 项），逐项给出默认值、语义与生效方式，并按场景给出可直接落地的生产配置模板；环境变量表以官方文档（2026-10-15 更新版）溯源，组织设置以实测实例逐项回读取证。

一、环境信息

本文基于的实测与取证环境：

• Seatsurfing 版本：1.136.3（ghcr.io/seatsurfing/backend:1.136.3，2026-10-23 发布）；
• 部署形态：Ubuntu 22.04 服务器上按《Seatsurfing 1.136 Docker Compose 部署指南》完成的双服务部署（应用 + PostgreSQL 18）；
• 环境变量来源：官方配置文档 seatsurfing.io/docs/self-hosted/config（页面更新时间 2026-10-15，查询日期 2026-10-24）；
• 组织级设置来源：本文实测实例的设置接口逐项回读（查询日期 2026-10-24，共 49 项，见第四章总览表）；
• 交互实例：管理后台（/ui/admin/）与 REST API（/setting/ 端点）。

本文使用的演示账号统一为 admin@seatsurfing.local / q1w2e3r4（部署时以 INIT_ORG_USER/INIT_ORG_PASS 指定的初始管理员）。

二、前置条件

1. 已按部署篇完成 Seatsurfing 1.136.3 安装并能登录管理后台（部署步骤与排障实录见《Seatsurfing 1.136 Docker Compose 部署指南》）；
2. 理解两层配置体系：部署级环境变量（进程启动时注入，改后需重建服务生效）与组织级业务设置（存数据库，管理后台或 API 实时改、实时生效）——两者职责不同，选错层是新手最常见的配置错误；
3. 本文涉及 API 调用的示例均需要管理员登录获取访问令牌（获取方式见《Seatsurfing 1.136 API 使用详解》认证一节，本文示例直接给出可执行的完整命令）。

三、参数查看与修改方式

3.1 部署级环境变量：查看、修改与生效方式

本节要做什么：弄清环境变量从哪里看、怎么改、何时生效。预期得到一套明确的变更操作序列。

查看当前注入值：进入 Seatsurfing 服务进程的运行环境（进入方式见《Seatsurfing 1.136 Docker Compose 部署指南》第十一章）后执行：

env | grep -E '^(POSTGRES_URL|PUBLIC_|INIT_ORG|CRYPT_KEY|JWT_)'

实测回显（本文实测实例）：

CRYPT_KEY=s9Kp2xQv7Rt4Zw8Yb3Nc6Mh1Jd5Fg0La
INIT_ORG_LANGUAGE=en
INIT_ORG_NAME=Quzuo Demo
INIT_ORG_PASS=q1w2e3r4
INIT_ORG_USER=admin
JWT_PRIVATE_KEY=/app/jwt.key
JWT_PUBLIC_KEY=/app/jwt.pub
POSTGRES_URL=postgres://seatsurfing:q1w2e3r4@db/seatsurfing?sslmode=disable
PUBLIC_PORT=8136
PUBLIC_SCHEME=http

修改与生效：环境变量在进程启动时读取一次，运行期不热加载。变更序列：改编排文件（或服务配置）的环境变量段 → 按部署篇的方式重建应用服务（数据库不动）→ 看启动日志确认无 ⚠️ Warning。注意 CRYPT_KEY 不可换（首启后已用其加密库内字段，换掉即读不回）；INIT_ORG_* 仅在空库首启生效，改了不报错也不生效（见 7.2 常见问题）。

3.2 组织级业务设置：管理后台与设置接口

本节要做什么：给出组织级设置的两条查看/修改通道（图形界面与接口），并用接口实测一条完整「读—改—回读—还原」流程。

通道一：管理后台。登录 http://<服务器地址>:8136/ui/admin/，Settings 区域按域分组（预订策略、公开预订、统计报表等）逐项可视改，保存即生效。

通道二：设置接口（组织管理员令牌）：

# 1) 读取全部组织设置（49 项，JSON 数组）
curl -s -H "Authorization: Bearer $JWT" http://localhost:8136/setting/ | python3 -m json.tool

实测回显（节选前 18 行）：

[
    {
        "name": "allow_any_user",
        "value": "1"
    },
    {
        "name": "allow_booking_nonexist_users",
        "value": "0"
    },
    {
        "name": "allow_recurring_bookings",
        "value": "1"
    },
    {
        "name": "booking_retention_days",
        "value": "365"
    },

# 2) 修改单项：PUT /setting/{name}，请求体 {"value":"..."}，成功返回 204
curl -s -o /dev/null -w '%{http_code}\n' -X PUT http://localhost:8136/setting/default_timezone \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"value":"Asia/Shanghai"}'

实测回显：

204

# 3) 回读确认生效
curl -s -H "Authorization: Bearer $JWT" http://localhost:8136/setting/ \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print([s for s in d if s['name']=='default_timezone'])"

实测回显：

[{'name': 'default_timezone', 'value': 'Asia/Shanghai'}]

还原默认值 Europe/Berlin（同样 PUT，返回 204）。值类型：设置项的值一律以字符串存取（布尔用 "0"/"1"，数字用十进制字符串，数组用 JSON 串）。

💡 说明：名称以 _sys_ 开头的设置项（如 _sys_version、_sys_org_primary_domain、_sys_install_id）是系统内部状态，不要手工修改。

四、参数总览

4.1 部署级环境变量总览（官方全表）

下表完整收录官方配置文档的环境变量清单（来源 seatsurfing.io/docs/self-hosted/config，查询日期 2026-10-24；类型与默认值照抄官方，语义解释为本文归纳）：

如何选层：涉及「进程怎么跑、连什么库、怎么收发邮件、怎么签发令牌」的用环境变量；涉及「预订策略、界面行为、租户功能开关」的用组织设置（4.2）。

4.2 组织级业务设置总览（实测 49 项全表）

以下为本文实测实例设置接口回读的全部组织级设置（查询日期 2026-10-24；值为全新初始化后的默认值）：

关键差异解读：feature_* 七项是租户级功能授权开关（与 SaaS 套餐/Plus Plugin 联动），自托管全量默认开启；真正要按业务收紧的是预订策略组（max_* / min_* / allow_* / public_booking_*）与隐私组（show_names、hide_reports/hide_stats）。

五、核心参数分类详解

5.1 数据库连接：POSTGRES_URL

标准连接串格式 postgres://<用户>:<密码>@<主机>:<端口>/<库名>?sslmode=disable。部署篇双件套部署中主机写服务名 db；独立数据库实例（DBA 托管 PostgreSQL 16/17）时写真实主机与端口。sslmode 参数属 PostgreSQL 标准连接参数：内网明文可用 disable；跨网段务必启用 TLS（verify-full + CA 证书）。本项为全部配置中的硬前提，启动日志 Database connection established. 即连接成功；失败时进程启动即退（排障见部署篇 11.1）。

💡 技术拓展：PostgreSQL 连接串的 sslmode 有六档——disable（不加密）、allow（先明文后协商）、prefer（先加密后降级）、require（加密不验证书）、verify-ca（加密验证 CA）、verify-full（加密验证 CA+主机名）。安全等级递增，跨公网连接选 verify-full，内网可选 require。本方案实测内网双件套部署采用 disable。

5.2 对外地址三件套：PUBLIC_SCHEME / PUBLIC_PORT / PUBLIC_LISTEN_ADDR

• PUBLIC_LISTEN_ADDR（默认 0.0.0.0:8080）是进程监听地址；PUBLIC_SCHEME/PUBLIC_PORT 是对外宣告的协议与端口，二者职责完全不同。系统发出的邀请/确认邮件链接、OAuth 回跳地址按 PUBLIC_SCHEME://<访问主机>:<PUBLIC_PORT> 拼接；
• 直连 HTTP 部署必须显式 PUBLIC_SCHEME=http 并把 PUBLIC_PORT 设为实际宿主端口（本文实测 8136）；官方默认 https/443 面向反代 TLS 终结场景——不设这两个变量且用反代时，务必确认反代对外就是 https/443，否则邮件外链端口错乱；
• 反代部署时通常只改 PUBLIC_SCHEME=https（PUBLIC_PORT 保持默认 443）。

5.3 初始化四件套：INIT_ORG_NAME / INIT_ORG_USER / INIT_ORG_PASS / INIT_ORG_LANGUAGE

仅在数据库为空、首次启动创建组织时生效。实测要点：INIT_ORG_USER=admin 的实际登录名是 admin@seatsurfing.local（域后缀固定，不是组织自定义域）；INIT_ORG_PASS 不设时用官方默认 Sea!surf1ng，登录后应立即改密（改密不影响该变量本身，二者此后无关）。

5.4 JWT 密钥：JWT_PRIVATE_KEY / JWT_PUBLIC_KEY（实测格式坑）

不设置时应用每次启动生成临时 RSA 密钥对，后果是每次服务重建全体用户会话失效（启动日志出现 ⚠️ Warning: No valid JWT_PRIVATE_KEY or JWT_PUBLIC_KEY set. Generating a temporary random private/public key pair …）。固定密钥的实测三步坑（全部真实回显，详见部署篇 11.3）：

1. 私钥必须是 PKCS1 传统格式（-----BEGIN RSA PRIVATE KEY-----）；OpenSSL 3.x 默认输出的 PKCS8（-----BEGIN PRIVATE KEY-----）实测报 x509: failed to parse private key (use ParsePKCS8PrivateKey instead for this key format)，用 openssl rsa -in jwt.key -traditional -out jwt-trad.key 转换；
2. 应用进程非 root 运行，密钥文件 600 权限实测报 open /app/jwt.key: permission denied，需 644；
3. 密钥路径不存在时容器运行时会把它建成目录，实测报 read /app/jwt.key: is a directory——挂载源必须真实存在。

正确配置后实测启动日志完全无 Warning。密钥固定后，服务每次重建都沿用同一密钥，既有登录会话不再失效——这正是固定密钥的目的。反之实测：密钥变更前签发的令牌在新密钥下访问接口返回 401（换密钥等于全体会话重置），因此密钥一旦固定就不要随意更换。

5.5 缓存：CACHE_TYPE 与 VALKEY_*

CACHE_TYPE=default 用应用内置缓存（单实例部署的默认正确选择）；CACHE_TYPE=valkey 切换外置 Valkey（Redis 兼容协议），配套 VALKEY_HOSTS（逗号分隔多主机）、VALKEY_USERNAME（默认 default）、VALKEY_PASSWORD。多实例横向扩展时必须切 valkey，否则各实例缓存不一致。

5.6 邮件发送：MAIL_SERVICE 与 SMTP_*

默认 MAIL_SERVICE=smtp 走 SMTP。标准内网中继：SMTP_HOST=<relay 地址>、SMTP_PORT=25 即可（不认证不加密）。官方文档给出的 Microsoft 365 推荐配置（照抄官方，查询日期 2026-10-24）：

MAIL_SERVICE=smtp
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_START_TLS=1
SMTP_AUTH=1
SMTP_AUTH_METHOD=LOGIN
SMTP_AUTH_USER=your-email@yourdomain.com
SMTP_AUTH_PASS=your-app-password
MAIL_SENDER_ADDRESS=your-email@yourdomain.com

官方安全注记（要点照抄）：尽量用应用专用密码而非常规密码；确保 STARTTLS 开启；生产严禁 SMTP_INSECURE_SKIP_VERIFY=1；确需明文 SMTP（本地投递）须显式 SMTP_START_TLS=0；SMTP_HOST 用 IP 地址时证书校验通常失败（证书签给域名），应改用主机名。官方另注明：1.121.1 起 STARTTLS 仅在 SMTP_START_TLS=1 时启用（不再因服务端宣告而自动启用）；对 M365 官方 SMTP 主机（smtp.office365.com、smtp-mail.outlook.com、outlook.office365.com）无论该开关如何都内部强制 STARTTLS。

备选通道 MAIL_SERVICE=acs 走 Azure Communication Services（配 ACS_ACCESS_KEY/ACS_HOST），适合已在 Azure 生态的组织。调试期可设 MOCK_SENDMAIL=1：邮件内容只写日志不实发，便于验证流程。

5.7 登录保护与限流

• 登录保护三参数：LOGIN_PROTECTION_MAX_FAILS=10 次（默认）失败、在 LOGIN_PROTECTION_SLIDING_WINDOW_SECONDS=600 秒滑动窗口内，封禁 LOGIN_PROTECTION_BAN_MINUTES=5 分钟。公网可访问的部署建议收紧（如 5 次/15 分钟/15 分钟）；
• API 限流：RATE_LIMIT=250（默认）每 RATE_LIMIT_PERIOD=1-M（1 分钟）。实测响应头可见限流状态：X-Ratelimit-Limit: 250、X-Ratelimit-Remaining: 248、X-Ratelimit-Reset: 1792819483——脚本对接 API 时应读取并尊重这三个头，超限后按 Reset 时间戳退避。

5.8 诊断与运行细节参数

• DEV=1：开发模式（含额外调试信息），官方明示生产禁用；
• DISABLE_VERSION_CHECK=1 / DISABLE_ANONYMOUS_USAGE_STATS=1：关闭更新检查与匿名统计，合规敏感环境建议都关（前者关闭会连带关掉后者）；
• DNS_SERVER：出站解析走指定 DNS（如内网 DNS 才能解析 SSO/SMTP 主机时设置）；
• FILESYSTEM_BASE_PATH / STATIC_UI_PATH：资源路径（默认即镜像内正确值，通常不动）；
• LISTEN_ADDR：官方 README 注记——IPv6-only 或多网卡环境下前端默认只绑一个接口，需要时设为 ::；
• CORS_ORIGINS：跨域来源白名单，API 对接自建前端/门户时配置。

5.9 特性开关：FEATURE_FLAGS

FEATURE_FLAGS 取逗号分隔列表，未知值忽略并打日志告警。官方支持三个（语义照抄官方文档）：

示例：FEATURE_FLAGS=ALLOW_ORG_DELETE,DOMAIN_VERIFICATION。安全建议：面向公网的部署开启 BLOCK_PRIVATE_OUTBOUND。

5.10 组织级预订策略详解（管理后台对应项）

组织级设置（4.2 表）中最常调整的一组是预订策略，实测语义归纳：

• 时间窗：max_days_in_advance=14 控制最早可提前天数；max_booking_duration_hours=12 单次上限；min_booking_duration_hours=0 单次下限；max_hours_before_delete + enable_max_hours_before_delete 组成「开始前 N 小时锁删」；
• 数量：max_bookings_per_user=10 每人进行中预订总数；max_concurrent_bookings_per_user=0 同时段并发（0 不限）；
• 模式：daily_basis_booking 切换按天整订（不选时段，适合全天数坐席制）；allow_recurring_bookings 循环预订（每周固定座位）；
• 审批与隐私：审批在空间级（requireApproval）配置而非组织级；show_names 控制订座是否互相可见真实姓名（默认匿名，注重隐私的团队保持 0）；
• 数据保留：booking_retention_enabled + booking_retention_days=365 自动清理过期预订数据（合规要求时启用）。

六、生产配置模板

适用场景：约 200 人混合办公企业、单台 8GB 内存 / 4 vCPU / NVMe SSD 服务器、Nginx 反代 TLS、企业 SMTP 中继、外置 PostgreSQL 16/17（或沿用双件套内嵌库）。环境变量段可直接落地（占位仅限必须按组织实际填写的凭据类）：

# --- 数据库 ---
POSTGRES_URL=postgres://seatsurfing:<数据库密码>@db-host:5432/seatsurfing?sslmode=verify-full
CRYPT_KEY=<32字节随机串，生成后妥善保管，永不再改>
# --- 对外地址（反代 TLS）---
PUBLIC_SCHEME=https
PUBLIC_PORT=443
# --- JWT 固定密钥（PKCS1 格式 PEM，见 5.4）---
JWT_PRIVATE_KEY=/app/jwt.key
JWT_PUBLIC_KEY=/app/jwt.pub
# --- 初始化（仅首启生效）---
INIT_ORG_NAME=Acme GmbH
INIT_ORG_USER=admin
INIT_ORG_PASS=<初始管理员密码>
INIT_ORG_LANGUAGE=zh
# --- 邮件（企业 SMTP 中继）---
SMTP_HOST=smtp.internal.example.com
SMTP_PORT=25
MAIL_SENDER_ADDRESS=no-reply@example.com
# --- 登录保护收紧 ---
LOGIN_PROTECTION_MAX_FAILS=5
LOGIN_PROTECTION_SLIDING_WINDOW_SECONDS=900
LOGIN_PROTECTION_BAN_MINUTES=15
# --- 合规与加固 ---
DISABLE_VERSION_CHECK=1
DISABLE_ANONYMOUS_USAGE_STATS=1
FEATURE_FLAGS=BLOCK_PRIVATE_OUTBOUND
# --- API 限流（默认即可，门户高并发对接时上调）---
RATE_LIMIT=250
RATE_LIMIT_PERIOD=1-M

⚠️ 上文 <数据库密码>/<初始管理员密码> 为凭据类占位，部署时以部署篇的环境变量注入机制赋真实值（凭据不入代码库）；其余值均可照抄。纯内网部署把 PUBLIC_SCHEME 改回 http 并按实际端口设 PUBLIC_PORT。

配套组织级设置建议（管理后台或 API 修改）：default_timezone 改为组织所在时区（如 Asia/Shanghai）；show_names 视隐私文化决定；max_days_in_advance 按行政规则调（坐席紧张的公司调小防囤座）；booking_retention_enabled=1 满足数据保留合规；公网部署保持 public_booking_enabled=0。

七、常见问题

Q1：改了环境变量为什么不生效？ 环境变量在进程启动时读取，运行期不热加载。改完必须重建服务（操作序列见部署篇第十章，等价于按新环境重起进程）。重建后看启动日志确认参数被接受（有误配置会打 ⚠️ Warning）。

Q2：改了 INIT_ORG_PASS 为什么管理员密码没变？ INIT_ORG_* 仅在空库首启创建组织时生效（官方文档明确：库里已有组织就不再初始化）。改密码走管理后台用户菜单；全新初始化只能清库重建（数据可弃时），见部署篇 11.5。

Q3：CRYPT_KEY 能换吗？ 不能随意换。它加密库内敏感字段，换新密钥后旧密文解不开。仅在清库重建时才用新值。

Q4：邮件发不出去怎么排查？ 按官方排障顺序：确认 M365 账号开启 SMTP AUTH；改用应用专用密码；防火墙放行出站 587；开启调试日志看 SMTP 会话；PLAIN/LOGIN 两种 SMTP_AUTH_METHOD 都试一遍。另注意 1.121.1 起必须显式 SMTP_START_TLS=1（不再自动启用），但 M365 官方主机内部强制 STARTTLS、该开关对其无效（官方文档原文语义）。

Q5：登录一直失败被拒？ 触发登录保护：LOGIN_PROTECTION_MAX_FAILS 次失败后封禁 LOGIN_PROTECTION_BAN_MINUTES 分钟（默认 10 次/5 分钟），等封禁过期或临时调大参数重建。生产建议按 5.7 收紧而非关闭。

Q6：开启纯 SSO（关闭密码登录）后管理员锁死了怎么办？ DISABLE_PASSWORD_LOGIN=1 前务必先配好并验证 SSO 身份源，且保留至少一个可经 SSO 登录的管理员。该项与 _sys_disable_password_login 组织设置联动，锁死时从数据库侧修正设置或回退该环境变量重建。

八、参考链接

• 官方环境变量文档（本文 4.1 全表来源）：https://seatsurfing.io/docs/self-hosted/config
• 官方自托管部署文档：https://seatsurfing.io/docs/self-hosted/docker
• 官方升级文档：https://seatsurfing.io/docs/self-hosted/upgrading
• 源码仓库：https://github.com/seatsurfing/seatsurfing
• 本专栏系列：《Seatsurfing 1.136 介绍与选型指南》、《Seatsurfing 1.136 Docker Compose 部署指南》、《Seatsurfing 1.136 配置参数详解》、《Seatsurfing 1.136 API 使用详解》