Wiki-Go 1.9.2 配置参数详解

目标：把 Wiki-Go 1.9.2 的 config.yaml 每一个参数的默认值、生效方式（重启/热更新）、实测行为与风险讲透。参数默认值取自官方源码 internal/config/config.go（v1.9.2 实查），总览表与落盘回显全部来自实测实例；改参验证走 settings API 与文件编辑双通道。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64），Wiki-Go v1.9.2（官方 release 二进制部署，监听 8080）
• 配置文件：/opt/wiki-go/data/config.yaml（服务工作目录 /opt/wiki-go）
• 默认账号：admin / q1w2e3r4（演示口令，改密过程见部署指南）
• 源码实查渠道：raw.githubusercontent.com/leomoon-studios/wiki-go/master/internal/config/config.go（直连 HTTP 200）
• 未完成部署的环境请先按 《Wiki-Go 1.9.2 Docker Compose 与二进制部署指南》 起一个实例（最小启动：cd /opt/wiki-go && ./wiki-go，明文 HTTP 需把 allow_insecure_cookies 改为 true 后重启）

二、前置条件

本文所有验证命令需要一个已登录的管理员会话与一个可写的配置文件：

cd /opt/wiki-go
curl -s -c jar -X POST http://127.0.0.1:8080/api/login -H 'Content-Type: application/json' -d '{"username":"admin","password":"q1w2e3r4","keepLoggedIn":false}'

{"message":"Login successful","success":true}

curl -s -b jar http://127.0.0.1:8080/api/check-auth

{"groups":null,"role":"admin","success":true,"username":"admin"}

三、参数查看与修改方式

Wiki-Go 的配置面只有三处，实测均可用：

3.1 文件通道：config.yaml

完整文件内容直接查看（实测节选，全量见 4.1 注）：

sed -n '1,30p' data/config.yaml

修改后 systemctl restart wiki-go（或直接重启二进制进程）生效。settings API 改过的键会原子回写到此文件（3.2 实测），文件是唯一的持久载体。

3.2 定位通道：-configfile 标志与 CONFIGFILE 环境变量

./wiki-go -h

Usage of ./wiki-go:
  -configfile string
    	where to find config.yaml (default "data/config.yaml")

这是 Wiki-Go 全部的命令行面（无其他子命令/标志，详见选型篇与 API 篇）。环境变量 CONFIGFILE 与标志同源（源码 GetEnvString("CONFIGFILE", config.ConfigFilePath)），标志优先级更高。

3.3 热更新通道：settings API（admin）

两组端点直接读写运行时配置并落盘：

curl -s -b jar http://127.0.0.1:8080/api/settings/wiki
curl -s -b jar http://127.0.0.1:8080/api/settings/security

{"title":"📚 Wiki-Go","owner":"wiki.example.com","notice":"Copyright :::year::: © All rights reserved.","timezone":"America/Vancouver","private":false,"disable_comments":false,"disable_file_upload_checking":false,"enable_link_embedding":false,"hide_attachments":false,"disable_content_max_width":false,"always_open_children_in_sidebar":false,"max_versions":10,"max_upload_size":10,"language":"en","languages":["ar","cs","da","de","en","es","fa","fi","fr","he","hi","it","ja","ko","nl","no","pl","pt","ru","sv","tr","zh-CN","zh-TW"],"log_level":"info"}

{"PasswordStrength":14,"login_ban":{"enabled":true,"max_failures":5,"window_seconds":180,"initial_ban_seconds":60,"max_ban_seconds":86400}}

⚠️ POST /api/settings/wiki 是全量覆盖语义：请求体没带的键按缺省处理，POST 前必须先 GET 拿全量再改（示例见 5.2）。实测改 timezone/language 后无需重启，配置立即落盘：

curl -s -b jar -X POST http://127.0.0.1:8080/api/settings/wiki -H 'Content-Type: application/json' -d '{"title":"📚 Wiki-Go","owner":"wiki.example.com","notice":"Copyright :::year::: © All rights reserved.","timezone":"Asia/Shanghai","private":false,"disable_comments":false,"disable_file_upload_checking":false,"max_versions":10,"max_upload_size":10,"language":"zh-CN","log_level":"info"}'
grep -nE 'timezone|language' data/config.yaml

{"message":"Settings updated successfully","success":true}
    timezone: "Asia/Shanghai"
    language: "zh-CN"

users / access_rules 两段没有独立文件 API，分别走 /api/users、/api/access-rules 端点管理并自动格式化回写 config.yaml（回显与落盘见 5.4/5.5）。

四、参数总览

4.1 五大段结构

实测 v1.9.2 完整 config.yaml（settings API 改过 timezone/language、开过 insecure cookie 之后的态）：

server:
    host: "0.0.0.0"
    port: 8080
    allow_insecure_cookies: true
    trusted_proxies: []
    ssl: false
    ssl_cert: ""
    ssl_key: ""
wiki:
    root_dir: "data"
    documents_dir: "documents"
    title: "📚 Wiki-Go"
    owner: "wiki.example.com"
    notice: "Copyright :::year::: © All rights reserved."
    timezone: "Asia/Shanghai"
    private: false
    disable_comments: false
    disable_file_upload_checking: false
    enable_link_embedding: false
    hide_attachments: false
    disable_content_max_width: false
    always_open_children_in_sidebar: false
    max_versions: 10
    max_upload_size: 10
    language: "zh-CN"
    log_level: "info"
security:
    passwordstrength: 14
    login_ban:
        enabled: true
        max_failures: 5
        window_seconds: 180
        initial_ban_seconds: 60
        max_ban_seconds: 86400
users:
    - username: admin
      password: $2a$14$.lDrECL9JY1Leqmkb/pKi.iAsbwrqQC8w.wtYr7ZvqNCi020iU8jy
      role: admin
access_rules: []

文件中的注释（官方模板自带）解释了 allow_insecure_cookies 的告警、trusted_proxies 的用法与 :::year::: 年份占位渲染，编辑时保留注释可自文档化。

4.2 默认值总表（源码 LoadConfig 实测抄录 + 本文验证列）

五、核心参数分类详解

5.1 server 段：监听与 Cookie 安全

• host / port：监听地址与端口。改端口实测（重启生效）：配置 port: 8145 后日志 HTTP server starting on 0.0.0.0:8145...；被占时报 listen tcp 0.0.0.0:8080: bind: address already in use 并退出。
• allow_insecure_cookies：默认 false（Cookie 带 Secure，只能 HTTPS 回传）。明文 HTTP 站点必须置 true，否则登录后任何二次请求都是 401。实测 netscape jar secure 列随配置从 TRUE 变 FALSE。⚠️ 官方注释明确警告：只在 homelab 一类可信网络开启。
• trusted_proxies：仅当直连来源在列表内才信任 X-Forwarded-For/X-Real-IP。官方注释给出单机 Nginx 反代填法 ["127.0.0.1"]；反代独立部署时填反代主机的实际 IP 或 CIDR。留空 = 不信任任何转发头（默认，安全）。
• ssl 三件套：原生 TLS，见 6.4。

5.2 wiki 段：站点与内容行为

• root_dir / documents_dir：数据根与文档子目录（相对值以进程工作目录为基准，如 /opt/wiki-go）。整站内容 = root_dir/documents_dir/<分类>/<文档>/document.md，实测建页 demo/t14-doc 落盘 data/documents/demo/t14-doc/document.md。
• title / owner / notice：浏览器标题、页脚归属与版权声明；notice 中 :::year::: 是 Wiki-Go 自己的年份替换记法（渲染时替换为当前年份），属合法配置值而非未赋值占位符。
• timezone：影响时间显示与版本快照文件名时间戳（版本 ts 实测按此时区换算，服务日志时间为 UTC 而快照名 20261102090837 对应 UTC 秒）。
• private：整站私有开关。实测置 true 后匿名访问渲染页与 /api/source/ 全部被拒、站点首页 303 跳登录；连已登录会话访问页面也返回 303（会话跳转登录确认）。置回 false 立即恢复 200。
• disable_comments：全站关闭评论区（默认 false；关闭后 comments 目录不再新增——机制位 settings GET 可见该键）。
• max_versions：每文档保留的历史快照数，默认 10；超出时按时间序清理最旧（源码 CleanupOldVersions，restore 时同样触发清理，实测恢复后快照集 +1）。置 0 关闭保存前快照。
• max_upload_size：附件上限（MB），默认 10；同时是导入 multipart 解析上限（源码 r.ParseMultipartForm(maxUploadSize)，实测超限上传会被拒）。
• disable_file_upload_checking：默认 false（做 mimetype 白名单校验）；官方支持扩展名实测见 README（jpg/png/svg/pdf/zip/docx/mp4 等）。
• language：界面语言。实测切 zh-CN 后新建文档的初始模板正文为「在此处输入内容。」（语言影响可见产物的一手证据）；languages 数组给出全部 24 个可选值（GET settings 实测）。
• log_level：debug|info|warn|error，默认 info（源码默认值实测）。
• enable_link_embedding / hide_attachments / disable_content_max_width / always_open_children_in_sidebar：编辑体验开关（剪贴板链接自动嵌入、隐藏附件区、解除 900px 正文宽度、侧栏子页常开），settings GET 全量回显可见。

💡 技术拓展：附件/上传校验策略存在多档——按扩展名白名单、按 mimetype 嗅探、完全放行。Wiki-Go 默认取「扩展名白名单 + 上传检查」双保险（disable_file_upload_checking: false 时生效）；只有内部可信来源才关检查。

5.3 security 段：口令哈希与登录封禁

• passwordstrength：bcrypt cost 因子，默认 14（实测 users 段哈希前缀即 $2a$14$）。cost 每 +1 哈希耗时翻倍；14 在登录侧仍有秒内响应（实测登录无感），调低会显著削弱离线爆破成本，不建议低于 12。

💡 技术拓展：口令哈希主流算法对比——

算法	特点	现状
bcrypt	可调 cost、抗 GPU 中等	Wiki-Go 所用（$2a$14$）
scrypt	内存硬化	参数组合复杂
Argon2id	内存+计算双硬化，OWASP 首推	更优但 Wiki-Go 未内置
PBKDF2	纯迭代、FIPS 友好	抗 GPU 最弱

本文实测所用为 bcrypt，cost 即 passwordstrength。

• login_ban.*：防爆破五连键。默认 enabled: true，window_seconds: 180 内 max_failures: 5 次失败触发封禁，initial_ban_seconds: 60 起、指数上探 max_ban_seconds: 86400（24h）。实测第 5 次错密后：

{"message":"Too many failed logins; try again later","retryAfter":60,"success":false}

且封禁期内正确密码同样 429（实测），生产上请给运维留跳板路径或按需调低 max_failures 的影响面。

5.4 users 段：角色与凭据

结构（实测 API 管理后自动格式化落盘）：

users:
    - username: admin
      password: $2a$14$<bcrypt哈希>
      role: admin

• role 三值：admin / editor / viewer（源码注释 + 实测 403/401 分层）；
• groups 可选，配合 access_rules 的组匹配（实测 editor 带 groups: [staff] 可写 restricted 路径，viewer 无组被拒）；
• 手工改文件与走 /api/users 等价，但改密/建号一律建议走 API（自动 bcrypt 哈希；文件里写明文口令不会生效）。

5.5 access_rules 段：路径级访问控制

实测通过 POST /api/access-rules 落盘的格式：

access_rules:
    - pattern: "/demo"
      access: restricted
      groups: [staff]
      description: "测试规则"

• pattern：文档路径前缀（/ 为首页）；
• access 三值：public（匿名可读）/ private（仅登录）/ restricted（仅指定组 + admin）；
• 实测 restricted 命中后：admin 读源 200、staff 组 editor 200、无组 viewer 401、匿名 401。
• ⚠️ 请求体必须扁平（pattern 直接在顶层），嵌套 rule:{...} 会返回 {"message":"Pattern is required","success":false}（实测 400）。

六、生产配置模板

6.1 内网小团队（1 GB 内存级主机、单实例、明文 HTTP 可控网段）

即默认模板 + 两处必改：allow_insecure_cookies: true（限内网）、private: true（整站需登录），语言与时区本地化：

wiki:
    timezone: "Asia/Shanghai"
    language: "zh-CN"
    private: true
    max_versions: 20
server:
    allow_insecure_cookies: true

适用：16 人以下协作知识库（平面文件全目录扫描式检索在千级页面内仍流畅；页面规模再大请先做导出备份演练）。

6.2 公网对外发布（Nginx 反代 TLS 终结）

server:
    host: "127.0.0.1"        # 仅监听回环，公网流量全部交给反代
    port: 8080
    allow_insecure_cookies: false
    trusted_proxies: ["127.0.0.1"]
wiki:
    private: false
security:
    login_ban:
        max_failures: 5
        initial_ban_seconds: 300

适用：前置 Nginx/Caddy 做 TLS 与限流，Wiki-Go 只做源站；initial_ban_seconds 拉到 300 提升公网爆破成本。

6.3 保守数据面（版本快照与附件）

wiki:
    max_versions: 50
    max_upload_size: 25
    disable_file_upload_checking: false

适用：文档合规要求高、磁盘充裕（每快照一个完整 .md 副本，50 版 × 平均 20 KB ≈ 每文档 1 MB 上界）。

6.4 原生 TLS 替代反代

server:
    ssl: true
    ssl_cert: "/opt/wiki-go/data/cert.pem"
    ssl_key: "/opt/wiki-go/data/key.pem"

证书私钥属敏感文件：由运维在 /etc/wiki-go/certs/ 下单独存放并以只读方式引用，勿提交进任何备份 zip 的外层仓库。官方 ssl compose 变体即此路线（见部署指南第六节）。

七、常见问题（FAQ）

7.1 settings POST 后其他键被重置了？

POST 是全量覆盖语义（3.3 ⚠️），先 GET 后改再 POST。

7.2 改了 config.yaml 不生效？

文件通道改动需要重启；只有 settings API 是热更新。log_level、监听类参数本就只在启动时读取。

7.3 手工编辑过的注释会不会丢？

settings API 回写由官方模板函数生成（源码 GetConfigTemplate/ensureCompleteConfig），实测经 API 修改后的文件保留原注释结构；直接编辑时缺键也会被自动补全（首启「配置不完整 → 补齐」行为，源码 ensureCompleteConfig）。

7.4 忘记 admin 口令怎么办？

编辑 data/config.yaml：把该用户 password 换成新口令的 bcrypt 哈希（可先用二进制形态零配置首启生成一个 admin/admin，抄它的哈希回填后重启——哈希串 $2a$14$ 前缀的两份实测样本见 4.1/5.2），或直接删 users 段让首启重建默认 admin/admin（删前备份 config.yaml）。

7.5 private 模式下机器人/采集怎么访问？

整站私有后匿名一律 303/401（实测）。给采集账号建 viewer 用户并按需对特定 pattern 设 public 规则，比关掉 private 更可控。

八、参考链接

• 配置结构源码：https://github.com/leomoon-studios/wiki-go/blob/master/internal/config/config.go
• 官方 README（配置章节）：https://github.com/leomoon-studios/wiki-go#configuration
• 部署与首启：《Wiki-Go 1.9.2 Docker Compose 与二进制部署指南》
• settings/users/access-rules 端点逐条实测：《Wiki-Go 1.9.2 API 使用详解》
• 组件定位与限制：《Wiki-Go 1.9.2 介绍与选型指南》