Otter Wiki 2.26.1 配置参数详解

目标：把 Otter Wiki 2.26.1 的配置体系一次讲透——环境变量 / Settings 界面 / settings.cfg 三个入口的分工与实测优先级，70 余个参数按站点身份、访问权限、注册邮件、Git 集成、页面仓库行为、界面侧栏、运行时安全分组逐项给出默认值与取值说明，并给出可直接投产的配置模板。全部回显与验证均在下述环境实测通过。

一、环境信息

• 操作系统：Ubuntu 26.04.1 LTS（x86_64，内核 7.0.0-38-generic）
• Docker 29.9.2 / Docker Compose v5.6.1
• Otter Wiki：2.26.1（官方镜像 redimp/otterwiki:2，构建标识 v2.26.1-0-gbb1aef4）
• 运行形态：Docker Compose 实例（宿主端口 8137 → 服务内 80，数据目录 /opt/otterwiki/app-data/；部署过程见 《Otter Wiki Docker Compose 部署指南》，下称「部署篇」）
• 演示账号：admin@otterwiki.local / q1w2e3r4（首个注册账号，自动 ADMIN）
• 官方配置参考实查日期：2026-10-29（otterwiki.com/Configuration 全表 + 2.26.1 源码 otterwiki/server.py 默认配置段核对）

二、前置条件

1. 一套按部署篇启动的 Otter Wiki 2.26.1 实例，健康状态确认：

cd /opt/otterwiki && docker compose ps --format '{{.Name}} {{.Status}}'

实测回显：

otterwiki-2.26.1-server Up 27 minutes (healthy)

2. 理解数据目录三件套的角色，配置最终都落在其中：

3. 管理员账号可登录（Settings 页面仅管理员可见）。

三、参数查看与修改方式

Otter Wiki 没有单一「主配置文件」，同一参数有三个入口，先分清层级再动手：

生效优先级（实测）：Settings 界面（数据库）> 环境变量 > settings.cfg。验证方法：先用环境变量 SITE_NAME=Ops Wiki 启动，再到 Settings 界面把站点名改成别的值保存、重启实例，日志出现明确的覆盖告警：

docker compose logs 2>&1 | grep -i overridden

实测回显：

[2026-10-29 23:12:57,199] WARNING in server: server: app.config["SITE_NAME"] set via environment variable is overridden by the database preference

即：界面上保存过的参数以数据库为准，环境变量只对「界面从未改过」的参数生效。因此推荐的分工是——环境变量管部署期基线，Settings 界面管运营期微调；两处都改过的参数以界面为准，排查「改了没生效」时先查这里（FAQ 问题 1）。

值类型规则（源码 server.py 实查 + 实测）：布尔型参数接受 true/yes/on/1（大小写不敏感）；整型参数传入非法值时忽略该值、回退默认并打 WARNING；字符串型原样传入。

四、参数总览

下表按功能域汇总全部可配置参数（默认值取自 2.26.1 官方镜像实测与官方 Configuration 页，镜像专属变量单独见 5.8 节）。第一列即环境变量名，三个入口同名。

4.1 站点身份

4.2 访问权限

三档取值：ANONYMOUS（任何人）< REGISTERED（登录用户）< APPROVED（被批准用户）。

4.3 注册与账户

4.4 邮件（SMTP）

4.5 Git 集成

4.6 页面与仓库行为

4.7 界面与侧栏

4.8 认证方式（外部反代认证）

4.9 运行时与安全

4.10 镜像专属变量（ Otter Wiki 应用不解析，由镜像 entrypoint/nginx 消费）

解读：4.1–4.9 为应用参数（三入口同名互通），4.10 为镜像参数（仅环境变量入口，改后需重建实例）。

五、核心参数分类详解

5.1 站点身份：SITE_NAME / SITE_LOGO / SITE_DESCRIPTION

站点名、副标题、Logo 支持环境变量与 Settings 界面双入口，界面优先（优先级实测见第三节）。典型部署先在 compose 里给基线：

    environment:
      - SITE_NAME=Ops Wiki
      - SITE_DESCRIPTION=Demo wiki powered by python, markdown and git

实测效果：浏览器标题栏与左上角显示 Ops Wiki；再在 Settings → Site 的界面里修改并保存后，数据库值覆盖环境变量（日志回显见第三节）。SITE_LOGO 可直接指向站内附件（如 //Home/a/logo.png 形式），实现零外链的品牌化。

5.2 访问权限三态：READ_ACCESS / WRITE_ACCESS / ATTACHMENT_ACCESS

三个权限档独立控制读、写、附件上传，出厂默认全部 ANONYMOUS（匿名访客可读写、可传附件），这是最容易踩坑的默认值。实测收紧为 REGISTERED 后重建实例：

      - READ_ACCESS=REGISTERED
      - WRITE_ACCESS=REGISTERED
      - ATTACHMENT_ACCESS=REGISTERED

匿名访问首页被 302 到登录页：

curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' http://127.0.0.1:8137/

实测回显：

302 -> http://127.0.0.1:8137/-/login?next=/?

同时 git 端点的匿名推送也被服务端 401 拒绝（回显见 FAQ 问题 2）。取值三档的含义：ANONYMOUS 完全公开（适合个人公开笔记）；REGISTERED 登录可读写（团队内网知识库最常用）；APPROVED 需管理员批准（配合 AUTO_APPROVAL=False 实现审核制注册）。本文演示环境为团队内网场景，生产模板采用 REGISTERED 三连（见第六节）。

5.3 注册与邮件：DISABLE_REGISTRATION 与 MAIL_* 组

邮件服务器（MAIL_SERVER 等）配好后，三类邮件才会工作：注册确认（EMAIL_NEEDS_CONFIRMATION=True 时）、管理员通知、密码重置。不配邮件的两条替代路径：其一，EMAIL_NEEDS_CONFIRMATION=False 允许注册即用（省确认环节）；其二，DISABLE_REGISTRATION=True 关闭自助注册，管理员用容器内 CLI 直接建号发密（命令与回显实测见《Otter Wiki 2.26.1 常用命令与页面语法详解》4.1 节，本文环境即用此法管理第二个账号）。Gmail 式 SMTP 的 settings.cfg 写法（官方 skeleton 原样）：

MAIL_SERVER = 'smtp.googlemail.com'
MAIL_PORT = 465
MAIL_USE_TLS = False
MAIL_USE_SSL = True
MAIL_USERNAME = 'MAIL_USERNAME'
MAIL_PASSWORD = 'MAIL_PASSWORD'

5.4 Git 集成：GIT_WEB_SERVER 与远端推送/拉取

GIT_WEB_SERVER=True 开启 git over HTTP 端点，URL 即站点根 /.git，克隆/推送认证用 wiki 邮箱+密码（HTTP Basic）。实测克隆与推送闭环、默认权限下的匿名行为，全部见《Otter Wiki 2.26.1 常用命令与页面语法详解》4.3 节，此处只讲配置面：

• 只读异地备份：仅开 GIT_WEB_SERVER，远端定时 git fetch 即可。
• 自动推送备份：GIT_REMOTE_PUSH_ENABLED=True + GIT_REMOTE_PUSH_URL=git@github.com:user/wiki.git + 私钥（正文或文件二选一），每次页面变更后自动推送到远端裸仓库。
• 双向同步：再加 GIT_REMOTE_PULL_ENABLED=True，远端仓库变更通过 webhook 触发拉取（配合 GIT_REMOTE_PULL_URL_SECURE=True 校验 HMAC 签名，webhook 地址形如 /-/api/v1/pull/<hash>）。

⚠️ 注意：GIT_ALLOW_EXTERNAL_SYMLINKS 保持默认 False。开启后版本库中的符号链接可以指向仓库外路径，仅在有明确可信数据来源时使用。

5.5 页面与仓库行为：RETAIN_PAGE_NAME_CASE 等

RETAIN_PAGE_NAME_CASE=False（默认）会把页面名统一小写落盘——实测创建页面 Team Handbook，版本库里落盘为：

ls /opt/otterwiki/app-data/repository/

实测回显：

home.md
opsrunbook.md
team handbook.md

即 URL 与文件名大小写不敏感，页面树中 Team Handbook 与 team handbook 是同一页；需要保留大小写（如代码类专有名词页面）时设 RETAIN_PAGE_NAME_CASE=True 并在部署初期决定，后期切换会产生页面改名历史。COMMIT_MESSAGE=REQUIRED（默认）强制保存时填写提交说明，这是 Otter Wiki 版本管理可用性的关键一环；自动化场景（脚本批量导入）可设 DEFAULT_COMMIT_MESSAGE='update %P at %Y-%m-%d' 类模板并配合 COMMIT_MESSAGE=DISABLED。

5.6 界面与侧栏：SIDEBAR_* 组

侧栏页面树默认 SIDEBAR_MENUTREE_FOCUS=SUBTREE（聚焦当前子树），页面多时避免侧栏爆炸；要全量目录改 OFF。SIDEBAR_CUSTOM_MENU 接受一段 Markdown 列表，渲染为侧栏自定义菜单区，配合 SIDEBAR_SHORTCUTS 控制默认快捷入口（默认 home pageindex createpage 三项）。HTML_EXTRA_HEAD/HTML_EXTRA_BODY 是官方给出的注入位（如埋点统计脚本），值会原样进每页 HTML。

5.7 运行时与安全：DEBUG / LOG_LEVEL / 数据库

DEBUG 生产保持 False（Flask 调试页会泄露源码上下文）；排查问题时临时开 LOG_LEVEL=DEBUG 观察渲染与权限判定，事后关回。数据库默认镜像内指向 sqlite:////app-data/db.sqlite，单机团队规模（千人内用户、万页内）完全够用；要多实例共享或企业级审计再切 PostgreSQL（SQLALCHEMY_DATABASE_URI 改连接串），切库前务必备份数据目录。

5.8 数据目录属主：PUID / PGID 与镜像变量

镜像 entrypoint 在启动时把容器内 www-data 用户的 uid/gid 改写为 PUID/PGID（默认 33/33），再 chown -R 数据目录——这是适配宿主机已有用户属主的通用手段。entrypoint 对 PGID=0 有硬性拒绝（原文）：

Fatal: PGID must not be 0 (root).

设置非默认值时 entrypoint 会先处理组冲突（官方注释为兼容 unraid 模板 PUID=99/PGID=100 而删除同名组）。改动后需 docker compose up -d 重建实例，并确认数据目录属主已变更（ls -la 属主列）。镜像专属变量（TZ/NGINX_MAX_UPLOAD 等）不进应用配置，只作用于进程与 nginx，全部仅环境变量入口。

六、生产配置模板

适用场景：10–100 人内网团队知识库，4 GB 内存 / 20 GB 磁盘，已有 SMTP，要求注册可控、数据有异地备份。完整 compose environment 段（可直接替换部署篇编排文件的 environment）：

    environment:
      - TZ=Asia/Shanghai
      - SITE_NAME=Team Wiki
      - SITE_DESCRIPTION=Internal knowledge base
      - READ_ACCESS=REGISTERED
      - WRITE_ACCESS=REGISTERED
      - ATTACHMENT_ACCESS=REGISTERED
      - AUTO_APPROVAL=True
      - EMAIL_NEEDS_CONFIRMATION=True
      - GIT_WEB_SERVER=True
      - GIT_REMOTE_PUSH_ENABLED=True
      - GIT_REMOTE_PUSH_URL=git@backup-host:wiki/otterwiki.git
      - GIT_REMOTE_PUSH_PRIVATE_KEY_FILE=/run/secrets/wiki_ssh_key
      - MAIL_DEFAULT_SENDER=wiki@example.com
      - MAIL_SERVER=smtp.example.com
      - MAIL_PORT=587
      - MAIL_USE_TLS=True
      - MAIL_USERNAME=${SMTP_USER}
      - MAIL_PASSWORD=${SMTP_PASS}
      - COMMIT_MESSAGE=REQUIRED

配套：NGINX_MAX_UPLOAD=20m（附件上限 20 MB 按需）；SMTP 账号密码属系统级真实凭据，用 ${SMTP_USER}/${SMTP_PASS} 占位并在同目录 .env 文件（chmod 600）注入；SSH 私钥用 docker secret 文件挂载。资源占用上该规模实例内存常驻约 200–300 MB，磁盘随附件增长，git 历史增量极小。

七、常见问题（FAQ）

Q1：环境变量改了没生效？ 先查是否被 Settings 界面的数据库偏好覆盖：docker compose logs | grep -i overridden，出现 overridden by the database preference 即是（实测回显见第三节）。处理：在 Settings 界面改回期望值，或从 db.sqlite 的 preferences 表删除对应记录。

Q2：收紧权限后匿名 git 推送被拒？ 这是预期行为。WRITE_ACCESS=REGISTERED 后 git-receive-pack 端点要求 Basic 认证，匿名推送实测报错：

fatal: could not read Username for 'http://127.0.0.1:8137': terminal prompts disabled

改用邮箱+密码认证推送即可（命令见命令详解篇 4.3 节）。

Q3：注册收不到确认邮件？ EMAIL_NEEDS_CONFIRMATION=True 但 MAIL_SERVER 为空时确认邮件发不出去。二选一：配好 SMTP（5.3 节），或内网无邮件时设 EMAIL_NEEDS_CONFIRMATION=False。

Q4：SECRET_KEY 在哪里、能改吗？ 首启自动写入 /app-data/settings.cfg（64 位十六进制随机串，实测见部署篇第八节）。它是会话签名密钥，更换后全体用户会话失效需重新登录；除怀疑泄露外不要动。

Q5：页面名大小写为什么「丢了」？ RETAIN_PAGE_NAME_CASE=False 默认把页面名小写化落盘（实测 Team Handbook → team handbook.md，见 5.5 节）。这是特性（URL 大小写不敏感），需保留大小写再开开关，且宜在部署初期决定。

Q6：匿名用户能直接改我的 wiki？ 默认三权限为 ANONYMOUS，公网部署必须收紧（5.2 节实测流程）；同时建议 DISABLE_REGISTRATION=True 或配邮件确认，防止陌生人自助注册获取写权限。

八、参考链接

• 官方 Configuration 全表：https://otterwiki.com/Configuration
• 官方 Installation 指南：https://otterwiki.com/Installation
• 源码仓库（otterwiki/server.py 为默认配置权威来源）：https://github.com/redimp/otterwiki
• Docker Hub（镜像与标签）：https://hub.docker.com/r/redimp/otterwiki

站内延伸阅读

• 《Otter Wiki Docker Compose 部署指南》：编排文件、首启初始化与数据持久化全景。
• 《Otter Wiki 2.26.1 常用命令与页面语法详解》：flask user 账户管理与 git 数据面运维实测。
• 《Otter Wiki 介绍与选型指南》：定位、架构与同类 Wiki 量化选型对比。