配置文件 config.yaml

所有平台共用同一份配置格式。交付包里的 config.example.yaml 逐项带注释，是权威模板；本页解释每个字段的含义、取值和配错时的表现。

文件位置与加载规则

文件名固定为 config.yaml，放在部署目录（与可执行文件同目录）。
程序先在当前工作目录找，找不到再找上一级目录。不能用命令行参数指定路径。
找不到文件时不会报错，而是全部使用默认值启动——jwt.secret 会是公开的默认值，这是生产事故，务必确认文件存在。
修改后必须重启才生效。
格式是 YAML：缩进只能用空格，key: value 的冒号后要有一个空格；值里含 #、:、@ 等字符时用双引号包起来。

首次部署从模板复制：

bash

cp config.example.yaml config.yaml          # Linux / macOS
copy config.example.yaml config.yaml        # Windows cmd

最小可用配置

使用内置 SQLite、不启用在线文档时，只需要这些：

yaml

server:
  port: "9000"

jwt:
  secret: "换成一串 32 位以上的随机字符"

license:
  path: ./data/license.lic
  webhook:
    type: feishu
    url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxxx"

log:
  level: info

生成随机密钥：

bash

openssl rand -hex 32                                   # Linux / macOS

powershell

-join ((48..57)+(97..102) | Get-Random -Count 64 | % {[char]$_})   # Windows PowerShell

字段说明

server

字段	默认值	说明
`server.port`	`"9000"`	监听端口。建议写成带引号的字符串。改端口后防火墙、反向代理、Docker 健康检查要一起改
`server.public_base_url`	空	对外可达的地址，如 `http://192.168.1.20:9000`。用于生成发给签署人的 H5 电子签名链接（二维码）。留空时按请求 Host 推断，多网卡或走反向代理时可能推断错，正式部署建议显式配置

jwt

字段	默认值	说明
`jwt.secret`	`change-me-in-production`	登录令牌签名密钥。必须修改，默认值是公开的，任何人都能伪造登录。修改后所有已登录用户需要重新登录

license

字段	默认值	说明
`license.path`	`./data/license.lic`	授权文件路径，相对路径按工作目录解析
`license.webhook.type`	—	`feishu`（飞书） / `dingtalk`（钉钉） / `custom`（自定义 HTTP）
`license.webhook.url`	空	机器人地址。配置后，授权到期前 30 / 15 / 7 / 3 / 1 天各推送一次提醒。留空则不提醒，强烈建议配置

log

字段	默认值	说明
`log.level`	`info`	`debug` / `info` / `warning` / `error`。环境变量 `APEXPM_LOG_LEVEL` 优先级更高，排查问题时可临时设成 `debug`

日志为 JSON 格式，写到标准输出，由启动方式决定落到哪里（apexpm.log、journald、docker logs、Windows 服务日志文件）。

database

不写这一段等同于使用 SQLite，数据库文件是 ./data/apexpm.db。接外部数据库时：

yaml

database:
  driver: postgres
  dsn: "postgres://apexpm:密码@127.0.0.1:5432/apexpm?sslmode=disable&TimeZone=Asia/Shanghai"
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: 30m

字段	默认值	说明
`database.driver`	`sqlite`	`sqlite` / `postgres` / `mysql` / `kingbase`。`dm`（达梦）当前可配但不可用，启动会直接报错
`database.dsn`	sqlite 时为 `./data/apexpm.db`	连接串。除 sqlite 外必填，漏配直接报错，不会回退到 sqlite。密码含特殊字符要 URL 编码（`@` → `%40`）
`database.max_open_conns`	`25`	最大连接数，不要超过数据库端的 `max_connections`
`database.max_idle_conns`	`10`	最大空闲连接数
`database.conn_max_lifetime`	`30m`	连接最长存活时间，应小于数据库或中间代理的空闲断连时间
`database.simple_protocol`	`false`	仅 postgres。经 pgbouncer transaction pooling 连接时必须设为 `true`

各数据库的建库要求与 DSN 格式见数据库选型与建库。

数据库一旦选定不要中途更换：各库之间没有自动数据迁移，换 driver 等于换成一个空库。

onlyoffice（可选）

不写这一段，在线文档功能禁用，其余功能不受影响。需要启用时联系我方获取网关地址与密钥。

yaml

onlyoffice:
  gateway_base: https://office.example.com   # 网关地址，两种存储模式都必填
  storage: local                              # local | oss

  # storage: local 时
  public_base: http://192.168.1.10:9000       # 本服务对网关可达的地址，不能写 localhost
  caller_sign_secret: "与网关一致的密钥"
  local:
    dir: ./data/documents

  # storage: oss 时
  oss:
    endpoint: oss-cn-hangzhou.aliyuncs.com    # 不带 bucket 名
    bucket: my-bucket
    access_key_id: ""
    access_key_secret: ""
    prefix: docs/                             # 必须与网关 OSS_PREFIX 一致

字段	说明
`gateway_base`	OnlyOffice 网关地址
`storage`	`local` 存本机磁盘；`oss` 存阿里云 OSS
`public_base`	local 模式：网关通过它下载源文件、回传编辑结果，必须是网关能访问到的地址
`caller_sign_secret`	local 模式：与网关 `CALLER_SIGN_SECRET` 一致
`local.dir`	local 模式：文档存储目录，默认 `./data/documents`
`oss.*`	oss 模式：必须与网关侧 `OSS_*` 指向同一个 bucket 与 prefix

环境变量覆盖

只有数据库相关的键和日志级别支持环境变量，适合容器部署时注入密码，优先级高于配置文件：

配置项	环境变量
`database.driver`	`APEXPM_DATABASE_DRIVER`
`database.dsn`	`APEXPM_DATABASE_DSN`
`database.max_open_conns`	`APEXPM_DATABASE_MAX_OPEN_CONNS`
`database.max_idle_conns`	`APEXPM_DATABASE_MAX_IDLE_CONNS`
`database.conn_max_lifetime`	`APEXPM_DATABASE_CONN_MAX_LIFETIME`
`log.level`	`APEXPM_LOG_LEVEL`

jwt.secret、license.*、server.* 等其余字段不支持环境变量，只能写在 config.yaml 里。

配置错误对照

配置问题都会让进程在启动时直接退出，日志里带 "message":"config load failed"：

日志中的 error	原因	处理
`While parsing config: yaml: line N: ...`	YAML 语法错误，通常是缩进用了 Tab、冒号后缺空格或值没加引号	按行号检查；可以用在线 YAML 校验工具核对
`database.dsn is required for driver "postgres"`	用了非 sqlite 驱动但没填 dsn	补上 `database.dsn` 或设置 `APEXPM_DATABASE_DSN`
`unsupported database.driver "xxx"`	driver 拼错或不支持	只能是 `sqlite` / `postgres` / `mysql` / `kingbase`
`database.driver "dm" is not available yet`	达梦暂不可用	改用其他数据库，或联系我方确认达梦支持进度
`time: invalid duration`	`conn_max_lifetime` 格式错	写成 `30m`、`1h` 这类带单位的值

还有两类问题不会报错，但同样要当心：

现象	原因
启动正常但数据是空的、之前配置不生效	工作目录不对，程序没找到 `config.yaml`，全部用了默认值
能登录，但之前签发的令牌全部失效	改了 `jwt.secret`。这是预期行为

配置文件 config.yaml ​

文件位置与加载规则 ​

最小可用配置 ​

字段说明 ​

server ​

jwt ​

license ​

log ​

database ​

onlyoffice（可选） ​

环境变量覆盖 ​

配置错误对照 ​

配置文件 config.yaml

文件位置与加载规则

最小可用配置

字段说明

server

jwt

license

log

database

onlyoffice（可选）

环境变量覆盖

配置错误对照