Gancio 1.28.2 配置参数详解

目标：Gancio 的「配置」分散在环境变量、config.json、数据库 settings 表三层，是部署后最容易踩坑的架构事实。本文基于 1.28.2 源码逐文件核对（server/config.js、server/initialize.server.js、server/cli.js、server/api/controller/{setup,settings}.js）与运行实例实测（settings 表 47 键全量导出、gancio settings CLI 实测回显、切换 PostgreSQL 完整演练），逐键讲清每层管什么、何时生效、怎么改。部署流程见《Gancio 1.28.2 Docker Compose 部署指南》。

一、环境信息

• 实测载体：Gancio 1.28.2（Docker Compose 部署，运行时 Node.js v20.19.6），宿主端口 8149 → 服务端口 13120，数据目录 /opt/gancio/data
• 源码取证：实例程序目录 /home/node/server/（grep -rn "process.env.GANCIO" server/ 全量结果）
• settings 取证：gancio settings list 全量导出（47 键）+ GET /api/settings（admin 身份）双通道核对
• PostgreSQL 切换演练：独立 compose 项目（gancio 1.28.2 + postgres:16），全流程实测后已销毁

二、三层配置模型总览

2.1 状态机：谁在什么阶段读哪层

源码实测的启动决策链（config.js 的 load() + initialize.server.js 的 start()）：

1. 进程启动读 -c 指定的配置文件（默认 /home/node/data/config.json）：
   • 文件存在 → status=CONFIGURED，配置以文件内容为准；
   • 文件不存在 → status=SETUP，日志打出 > Configuration file does not exists...（实测首启回显）。
2. CONFIGURED 路径：连库 → 跑增量迁移 → 加载 settings 表 → status=READY，对外提供完整服务。
3. SETUP 路径：若环境变量 GANCIO_DB_DIALECT 存在，则用 GANCIO_DB_* 组装数据库连接并执行建库迁移（状态转为 DBCONF，此时不写 config.json）；否则等待网页向导。
4. 初始化收尾（网页向导或 POST /api/setup/restart）：把本次请求的协议 + Host 头写入 baseurl/hostname，落盘 config.json，创建 admin 随机密码账号，进程自杀，由 restart: always 拉起进入 READY。

💡 实测佐证：PostgreSQL 演练中用 Host: gancio.test 头调用 POST /api/setup/restart，生成的 config.json 即为 "baseurl": "http://gancio.test", "hostname": "gancio.test"——首启时用什么地址访问，站点地址就被写成什么，之后要改只能改 settings（见 5.3）。

2.2 三层分工表

三、环境变量层

3.1 有效的 17 个变量（源码逐一实证）

grep -rn "process.env.GANCIO" server/ 实测仅命中以下变量（文件与行号来自 1.28.2 源码）：

3.2 无效变量陷阱（高频踩坑）

社区流传的 compose 示例（含部分博客模板）常带以下变量，在 1.28.2 全部源码中零引用，设置不会有任何效果：

⚠️ 本文部署时的实测反例：compose 里设了 GANCIO_LOCALE=zh、GANCIO_TIMEZONE=Europe/Rome，界面语言与时区最终生效靠的是 settings 表中 instance_locale: "zh"、instance_timezone: "Europe/Rome" 两键（gancio settings list 实测），与环境变量无关。源码层证据：initialize.server.js 用 settings.instance_locale/instance_timezone 设置 Luxon 的 Settings.defaultLocale/defaultZone。

四、config.json 层

4.1 实测全量内容与逐键解读

初始化后生成的 /opt/gancio/data/config.json（实测原文，节选合并）与逐键说明：

4.2 修改方式与优先级

• 直接编辑文件后重启服务：docker compose restart gancio。
• 优先级实测结论：config.json 存在时（CONFIGURED），数据库连接以文件为准，改 compose 里的 GANCIO_DB_* 不会生效（源码路径：仅 SETUP 分支读 DB 环境变量）。换库要么删/改 config.json 的 db 段，要么全新初始化。
• CLI 与进程都支持 -c/--config 指定其他配置文件路径（gancio --help 实测默认 /home/node/data/config.json）。

五、settings 层：数据库站点设置 47 键

5.1 查看通道（实测三选一）

docker exec --workdir /home/node/data gancio gancio settings list          # CLI 全量导出
docker exec --workdir /home/node/data gancio gancio settings get title     # 单键
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8149/api/settings  # API（admin）

管理界面（登录后 Admin → Settings）同样读写这张表。实测 CLI 与 API 两通道输出一致，共 47 个键；另有联邦私钥 privateKey 存库但 CLI 列表不回显（初始化日志中打码为 SET privateKey *****）。

5.2 全量键分组详解（实测值即 1.28.2 出厂默认）

站点基本（8 键）

活动能力（10 键）

地图与地理编码（5 键，默认关）

联邦（5 键）

界面外观（11 键）

通知与插件（8 键）

密钥（1 键）

5.3 修改 settings 的正确姿势（实测两大坑）

CLI 修改（值必须是合法 JSON）：

docker exec --workdir /home/node/data gancio gancio settings set title '"Quzuo 社区日历"'

实测回显：

title
Old value: "Quzuo 社区日历"
New value: "Quzuo 社区日历"

Note that a restart is needed to get the new setting

⚠️ 坑 1（JSON 值）：直接传裸字符串会被 JSON.parse 拒绝，实测报错：

SyntaxError: Unexpected token '排', "排错测试" is not valid JSON
    at Object.set [as handler] (/home/node/server/cli/settings.js:42:53)

正确形态是「外层 shell 引号 + 内层 JSON 双引号」：字符串 ' "值" '、布尔 'true'、数组/对象 '["a","b"]'。

⚠️ 坑 2（键名）：键名以 settings list 为准，猜键名会撞墙，实测：

gancio settings set locale zh
Setting "locale" does not exists

（语言键是 instance_locale，不是 locale。）

改完必须重启才生效（回显原文 Note that a restart is needed）：docker compose restart gancio。

反代上线后改站点地址的标准三连（实测命令形态）：

docker exec --workdir /home/node/data gancio gancio settings set baseurl '"https://gancio.example.org"'
docker exec --workdir /home/node/data gancio gancio settings set hostname '"gancio.example.org"'
docker compose restart gancio

六、切换 PostgreSQL 实测演练

小规模社区 SQLite 够用；投稿频繁（SQLITE_BUSY 重试顶到 15 次）或数据量上来时切 PostgreSQL。官方模板即 DB=postgres 一份 compose（sqlite/postgres/mariadb 三选一）。以下为本文独立环境的全流程实测。

6.1 演练 Compose（gancio + postgres:16 双服务）

name: gancio-pgtest

services:
  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=gancio
      - POSTGRES_PASSWORD=gancio
      - POSTGRES_DB=gancio
    volumes:
      - pgdata:/var/lib/postgresql/data

  gancio:
    image: cisti/gancio:1.28.2
    restart: always
    depends_on:
      - db
    environment:
      - GANCIO_DATA=/home/node/data
      - NODE_ENV=production
      - GANCIO_DB_DIALECT=postgres
      - GANCIO_DB_HOST=db
      - GANCIO_DB_PORT=5432
      - GANCIO_DB_DATABASE=gancio
      - GANCIO_DB_USERNAME=gancio
      - GANCIO_DB_PASSWORD=gancio
    volumes:
      - ./data:/home/node/data

volumes:
  pgdata:

6.2 首启自动建库（实测日志）

docker compose up -d

实测 gancio 首启直接连上 PG 并跑完 54 个迁移：

debug: Connecting to DB: {"dialect":"postgres","storage":"","host":"db","port":"5432","database":"gancio","username":"gancio","password":"gancio","logging":false,"dialectOptions":{"autoJsonMap":true}}
debug: == 20191025133803-tags: migrating =======
debug: == 20191025133803-tags: migrated (0.016s)
...
debug: == 20250324211014-to_notify: migrating =======
debug: == 20250324211014-to_notify: migrated (0.003s)

注意 "storage":""——非 sqlite 方言时 storage 被源码强制置空（setup.js _setupDb 实测逻辑）。

6.3 初始化与就绪验证（实测）

演练环境无浏览器，用 POST /api/setup/restart 完成收尾（Host 头即被写入站点地址）：

HTTP 200 {"password":"g3jq3j3gqhkv","email":"admin"}

服务被 restart: always 拉起后探活：

HTTP 200 OK

生成的 config.json 数据库段实测：

"db": {
  "dialect": "postgres",
  "storage": "",
  "host": "db",
  "port": "5432",
  "database": "gancio",
  "username": "gancio",
  "password": "gancio",
  "logging": false,
  "dialectOptions": { "autoJsonMap": true }
}

数据库侧确认建表（psql -U gancio -d gancio -c '\dt' 实测节选）：

 public | SequelizeMeta | table | gancio
 public | announcements | table | gancio
 public | ap_users      | table | gancio
 public | collections   | table | gancio
 public | event_tags    | table | gancio
 public | events        | table | gancio
 public | filters       | table | gancio
 public | instances     | table | gancio
 public | messages      | table | gancio

演练环境验证后已整体销毁（docker compose down -v）。

6.4 存量实例迁移提醒

• 环境变量只在「无 config.json」的初始化阶段参与建库：存量实例改 compose 的 GANCIO_DB_* 无效（见 4.2），需改 config.json 的 db 段并重启。
• 官方文档只提供安装期三选一（sqlite/postgres/mariadb 模板），未提供 SQLite→PostgreSQL 的存量数据转换工具；小数据量可用 API 导出导入（/api/export/json 实测存在）重建，量大则需自行做库间迁移并充分演练。

七、常见配置陷阱速查

八、参考链接

• 官方配置文档：https://gancio.org/v1/install/config
• 官方 Docker 安装页（compose 模板三选一）：https://gancio.org/v1/install/docker
• 官方 Nominatim 自建指引：https://gancio.org/v1/install/nominatim
• 官方 Custom CSS / Custom Javascript 指引：https://gancio.org/v1/usage/custom_css
• 上游源码 server/config.js、server/initialize.server.js、server/api/controller/setup.js：https://framagit.org/les/gancio

站内相关阅读：

• 《Gancio 介绍与选型指南》：架构总览与选型
• 《Gancio 1.28.2 Docker Compose 部署指南》：部署与初始化流程
• 《Gancio 1.28.2 常用 CLI/运维命令详解》：CLI 命令与日常运维