Outline Server 配置参数详解

定位：逐项讲清 Outline Server v1.12.3 在服务器上的全部配置面——接入凭据、服务器级配置、访问密钥库、数据面后端配置、证书、指标采集与安装器级参数，并给出每项参数的实测查看/修改方式。所有文件内容与命令输出均在 Ubuntu 22.04.5 LTS 实测环境逐字采集（2026-10-20），安装过程见《Ubuntu 22.04 安装 Outline Server 指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（Jammy），x86_64
• 软件版本：Outline Server v1.12.3（官方安装脚本部署，stable 通道，2026-10-20 实测；服务端 API 自报版本 "version":"1.12.3"）
• 实测端口：管理端口 15490（TCP），访问密钥端口 15491（TCP+UDP）
• 状态目录：/opt/outline
• 实测时点密钥规模：3 个访问密钥（id 0/1/3，含 1 个改名密钥）
• 服务器对外地址：10.0.0.2（实测环境 IP，生产环境为服务器公网 IP）
• 溯源补充：安装器行为与参数取值均对官方 install_server.sh 源码取证（2026-10-20）

二、前置条件

1. 已按《Ubuntu 22.04 安装 Outline Server 指南》完成安装并确认服务健康（管理 API 可响应）；
2. 服务器本地 root 或 sudo shell；
3. 准备好管理 API 访问要素（都在 /opt/outline/access.txt）：

# 读取管理 API 凭据
cat /opt/outline/access.txt

实测回显：

certSha256:81780C5EA71D32AA05EF34D1B302BA3A5EE26F327CD787C337FFB23889A5FEBE
apiUrl:https://10.0.0.2:15490/nSSFAqF32yf3eH7IbaMHKg

💡 说明：上例为首次安装时点凭据；本文后续示例使用实测环境重装后的当前凭据（前缀 81XKB8WldZi-_V92KSKvsQ），读者以自己 access.txt 的值为准。apiUrl = https://<服务器地址>:<管理端口>/<秘密前缀>，调用管理 API 时必须附带服务器自签证书做校验（curl --cacert，详见《Outline Server 管理 API 使用详解》）。

三、参数查看与修改方式

Outline Server 的配置有两条查看/修改路径，本篇两条都讲，并以实测标明各自边界：

⚠️ 注意：服务实例由官方安装器自动托管（自动重启、随系统自启、每小时自动检查更新）。修改配置请一律走管理 API：文件直改的生效条件与回写时机属受管运行时内部行为，官方未提供手工编辑文件的支持路径；直接改文件可能与管理 API 的持久化机制冲突。

四、参数总览

五、核心参数分类详解

5.1 接入凭据（access.txt）

安装器把 Manager 接入凭据写入 /opt/outline/access.txt（另有同内容备份 access.txt.bak）：

cat /opt/outline/access.txt

实测回显：

certSha256:81780C5EA71D32AA05EF34D1B302BA3A5EE26F327CD787C337FFB23889A5FEBE
apiUrl:https://10.0.0.2:15490/nSSFAqF32yf3eH7IbaMHKg

• apiUrl：管理 API 完整地址。路径尾段（如 nSSFAqF32yf3eH7IbaMHKg）是安装时由 /dev/urandom 取 16 字节随机数生成的秘密前缀（安装器源码 head -c 16 /dev/urandom | safe_base64，2026-10-20 取证），等效于管理 API 的"口令"——泄露即等于管理权泄露，请勿外传该文件；
• certSha256：自签证书指纹，Manager 接入时做证书固定校验。与证书文件指纹一致（见 5.4 节 openssl 实测）；
• 轮换行为（实测）：重跑安装脚本会重新生成秘密前缀与证书，apiUrl/certSha256 全部变化，Outline Manager 需重新接入；已建访问密钥保留（实测记录见安装指南 10.2 节）。

5.2 服务器级配置（shadowbox_server_config.json）

文件实测全文（本实测时点，已通过 API 改名为 outline-demo-server）：

cat /opt/outline/persisted-state/shadowbox_server_config.json

实测回显：

{"portForNewAccessKeys":15491,"hostname":"10.0.0.2","serverId":"db7d0e08-70c8-47ec-a256-5be6c01e4219","metricsEnabled":false,"createdTimestampMs":1792508135464,"name":"outline-demo-server"}

逐项说明与修改方式：

文件字段与管理 API 字段的对应关系（GET /server 实测返回体）：

curl --cacert /opt/outline/persisted-state/shadowbox-selfsigned.crt \
  https://10.0.0.2:15490/81XKB8WldZi-_V92KSKvsQ/server

实测回显：

{"name":"outline-demo-server","serverId":"db7d0e08-70c8-47ec-a256-5be6c01e4219","metricsEnabled":false,"createdTimestampMs":1792508135464,"version":"1.12.3","portForNewAccessKeys":15491,"hostnameForAccessKeys":"10.0.0.2"}

💡 说明：API 视图比文件多两个字段——version（实装版本，排查版本最直接）与 hostnameForAccessKeys（对外地址的 API 命名）；version 只读。

5.3 访问密钥配置（shadowbox_config.json 与 outline-ss-server/config.yml）

密钥体系涉及两个落盘文件：密钥库（唯一事实源）与数据面后端配置（由密钥库同步生成，供 outline-ss-server 后端实际加载）。

密钥库实测全文：

cat /opt/outline/persisted-state/shadowbox_config.json

实测回显：

{"accessKeys":[{"id":"0","name":"","password":"TjDlqvxukYzNcvTPW4qtsV","port":15491,"encryptionMethod":"chacha20-ietf-poly1305"},{"id":"1","name":"office-test-key","password":"zmhZ2Fwh6qDo4eLXGvDnye","port":15491,"encryptionMethod":"chacha20-ietf-poly1305"},{"id":"3","name":"","password":"S3t6wbmWLcfJWAIDpiwqBI","port":15491,"encryptionMethod":"chacha20-ietf-poly1305"}],"nextId":4}

数据面后端配置实测全文（与密钥库逐密钥对应）：

cat /opt/outline/persisted-state/outline-ss-server/config.yml

实测回显：

keys:
  - cipher: chacha20-ietf-poly1305
    id: '0'
    port: 15491
    secret: TjDlqvxukYzNcvTPW4qtsV
  - cipher: chacha20-ietf-poly1305
    id: '1'
    port: 15491
    secret: zmhZ2Fwh6qDo4eLXGvDnye
  - cipher: chacha20-ietf-poly1305
    id: '3'
    port: 15491
    secret: S3t6wbmWLcfJWAIDpiwqBI

字段逐项：

⚠️ 注意：password/secret 即代理凭据，本文示例为实测环境临时密钥（收工后实测环境整体销毁），生产环境请按密钥管理规范保管 /opt/outline 目录（建议 chmod 收紧至管理员可读，删除前先备份）。

5.4 证书与私钥（shadowbox-selfsigned.crt / .key）

管理 API 的 TLS 证书为安装器生成的自签证书（用途：管理端口 HTTPS + Manager 证书固定）：

openssl x509 -in /opt/outline/persisted-state/shadowbox-selfsigned.crt \
  -noout -subject -dates -fingerprint -sha256

实测回显：

subject=CN = 10.0.0.2
notBefore=Oct 20 14:47:00 2026 GMT
notAfter=Sep 26 21:47:00 2126 GMT
sha256 Fingerprint=81:78:0C:5E:A7:1D:32:AA:05:EF:34:D1:B3:02:BA:3A:5E:E2:6F:32:7C:D7:87:C3:37:FF:B2:38:89:A5:FE:BE

• CN = 对外地址（安装时 --hostname 值，本例 10.0.0.2）；
• 有效期 100 年（安装器源码 -days 36500，2026-10-20 取证），密钥为 RSA-4096（源码 -newkey rsa:4096 取证）；
• sha256 Fingerprint 与 access.txt 的 certSha256 一致（本例 81780C...FEBE）；
• 轮换（实测）：重跑安装脚本重新生成证书与私钥（指纹随之变化，见安装指南 10.2 节）；私钥文件权限 -rw-------（仅 root 可读，实测 ls -la）。

5.5 指标采集配置（prometheus/config.yml）

内置指标链路的采集配置（属受管运行时范畴，一般无需改动）：

cat /opt/outline/persisted-state/prometheus/config.yml

实测回显（输出节选）：

# sc：本机内部指标抓取（仅回环地址）
scrape_configs:
  - job_name: shadowbox
    scrape_interval: 30s
    metrics_path: /metrics
    static_configs:
      - targets:
          - '127.0.0.1:9090'
  - job_name: restapi
    static_configs:
      - targets:
          - '127.0.0.1:9091'
  - job_name: ss
    static_configs:
      - targets:
          - '127.0.0.1:9092'

💡 说明：三个内部指标端点（9090/9091/9092）只绑定回环地址，不对外暴露。对外的指标查询一律走管理 API：按密钥流量 GET /metrics/transfer、实验性服务器指标 GET /experimental/server/metrics?since=（实测回显见《Outline Server 管理 API 使用详解》）。

5.6 安装器级参数（安装时决定，重装变更）

以下参数在执行 install_server.sh 时给定，安装后如需变更需重跑安装脚本（行为实测见安装指南 10.2 节）：

⚠️ 注意：安装器还会在生成服务实例启动配置时注入一组运行时环境变量（管理端口、秘密前缀、证书路径、指标上报地址、状态目录等），属受管运行时范畴，由安装器自动生成与消费，管理员无需也不应手工编辑。

六、场景化配置建议

场景 A：个人自用（最小暴露面）

1. 管理端口保持默认随机或指定高位端口，云安全组仅放行自己的常用出口 IP；
2. 服务器改名便于识别：PUT /name；
3. 关闭匿名指标上报（保持默认 false，实测确认默认值为 false）；
4. 密钥即用即删：给设备生成独立密钥，设备退役即 DELETE /access-keys/<id>。

场景 B：小团队分发（10~50 人）

1. 对外地址用域名（PUT /server/hostname-for-access-keys 指定；注意仅对新密钥生效，存量密钥需删除重建）；
2. 为全体密钥设置默认流量上限：PUT /server/access-key-data-limit（如 10GB），个别重度用户单独覆盖后按需解除（实测路径 PUT/DELETE /access-keys/<id>/data-limit）；
3. 定期用 GET /metrics/transfer 查看各密钥用量（实测回显见管理 API 篇）；
4. 密钥端口 UDP 与 TCP 都要在安全组放行（UDP 中继需要）。

场景 C：同机多套环境（测试/生产隔离）

1. 用多实例参数安装第二实例（独立状态目录与端口对）；
2. 两实例凭据/密钥/证书完全独立，互不影响；
3. 指定版本部署用 SB_IMAGE（版本锁定），注意自定义版本时自动更新间隔变为 30 秒（源码取证），测试环境如不希望频繁拉取可评估后使用。

七、常见问题（FAQ）

Q1：改了对外地址/端口后，旧密钥的连接信息没变？ 设计行为（实测确认）：PUT /server/hostname-for-access-keys 与 PUT /server/port-for-new-access-keys 只作用于之后新建的密钥，既有密钥保持原值并在原端口继续服务（实测旧密钥端口仍在监听）。需要存量密钥迁移时：记录旧密钥的 password → 删除旧密钥 → 用密钥导入接口按原凭据在新端口重建（接口见管理 API 篇）。

Q2：直接编辑 /opt/outline/persisted-state/ 下的 JSON/YAML 文件改配置行不行？ 不建议。服务实例由官方安装器自动托管，文件直改的生效与回写时机不受支持，可能与管理 API 的持久化机制冲突；配置修改的官方支持路径是管理 API（本篇 5.2/5.3 各项均给出实测 API 修改方式）。文件仅作只读巡检与备份用途。

Q3：重跑安装脚本后，服务器名称和接入凭据怎么都变了？ 实测行为（安装指南 10.2 节）：重装会重置服务器级配置（名称回到默认 Outline Server）并重新生成秘密前缀与证书（apiUrl/certSha256 全变，Manager 需重新接入）；访问密钥保留。变更前请先记录自定义配置。

Q4：metricsEnabled 打开后会上报什么？ 匿名聚合指标（不含用户内容），用于官方服务质量统计；开关状态即时生效（实测 PUT /metrics/enabled 后 GET /metrics/enabled 立即读回）。默认关闭。

Q5：怎么确认当前实装版本？ 管理 API 直接返回版本号：GET /server 的 "version":"1.12.3" 字段（本篇 5.2 节实测回显），比查文件更直接。

Q6：--api-port 与 --keys-port 能否相同？ 不能。实测报错：

--api-port must be different from --keys-port

Sorry! Something went wrong. If you can't figure this out, please copy and paste all this output into the Outline Manager screen, and send it to us, to see if we can help you.
Full log: /tmp/outline_log25hUsg4jeg

八、参考链接

• 安装实测（本仓姊妹篇）：《Ubuntu 22.04 安装 Outline Server 指南》
• 管理 API 详解（本仓姊妹篇）：《Outline Server 管理 API 使用详解》
• 介绍与选型（本仓姊妹篇）：《Outline Server 介绍与选型指南》
• 上游仓库：https://github.com/OutlineFoundation/outline-server
• v1.12.3 服务端源码：https://github.com/OutlineFoundation/outline-server/tree/server-v1.12.3/src/shadowbox
• 官方安装脚本：https://raw.githubusercontent.com/Jigsaw-Code/outline-server/master/src/server_manager/install_scripts/install_server.sh