Realms Wiki setup配置向导详解：realms-wiki.json全部配置项完整指南

Realms Wiki 是一款用 Python 编写的基于 Git 的 Wiki 系统，realms-wiki.json 配置文件是它部署与定制的核心。本文将带你完整走一遍 realms-wiki setup 交互式配置向导，并逐一讲解 realms-wiki.json 中的全部配置项，帮助你快速搭建并调优属于自己的 Wiki。

一、配置体系总览：realms-wiki.json 从哪里来？

Realms Wiki 的配置遵循「三层覆盖」规则，理解它就能看懂所有行为差异：

优先级	来源	说明
高	环境变量（REALMS_ 前缀）	如 REALMS_DB_URI、REALMS_WIKI_PATH
中	realms-wiki.json 文件	setup 向导生成的配置文件
低	内置默认值	定义在 realms/config/init.py

配置文件会被程序按以下顺序查找，找到即用（见 realms/config/init.py 中的 get_path()）：

1. 当前工作目录 ./realms-wiki.json
2. 用户主目录 ~/realms-wiki.json
3. 系统目录 /etc/realms-wiki/realms-wiki.json（推荐的生产位置）

💡 向导结束时若提示 You can move file to /etc/realms-wiki/realms-wiki.json，就是建议你采用第 3 种位置。

二、一键启动：realms-wiki setup 配置向导

安装完成后（pip install realms-wiki），只需一条命令进入向导：

realms-wiki setup

向导会依次询问以下问题（源码见 realms/commands.py 的 setup 函数），直接回车即采用默认值：

向导提问	对应配置项	默认值
Enter site title	SITE_TITLE	Realms
Enter base URL	BASE_URL	http://localhost
Enter port number	PORT	5000
Enter secret key	SECRET_KEY	自动生成随机 64 位字符串
Enter wiki data directory	WIKI_PATH	/tmp/wiki
Allow anonymous edits?	ALLOW_ANON	True
Enable registration?	REGISTRATION_ENABLED	True
Cache type?	CACHE_TYPE	simple（可选 simple / redis / memcached）
Search type?	SEARCH_TYPE	simple（可选 simple / whoosh / elasticsearch）
Database URI	DB_URI	sqlite:////tmp/wiki.db

向导会根据选择追加提问并自动安装依赖：

• 选了 redis → 追问 CACHE_REDIS_HOST / CACHE_REDIS_PORT / CACHE_REDIS_PASSWORD / CACHE_REDIS_DB，并自动 pip install redis；
• 选了 memcached → 追问 CACHE_MEMCACHED_SERVERS（空格分隔多个服务器）；
• 选了 elasticsearch → 追问 ELASTICSEARCH_URL；
• 选了 whoosh → 自动 pip install Whoosh。

结束后向导会提示启动方式：

realms-wiki start    # 守护进程方式启动
realms-wiki dev      # 开发模式（前台、自动重载）

完成配置后记得先建库再启动：realms-wiki create_db。

三、realms-wiki.json 全部配置项完整清单

以下内容与 realms/config/init.py 中的 Config 类完全对应，未写入 json 的项均使用默认值。

1️⃣ 基础信息

配置项	默认值	作用
SITE_TITLE	Realms	站点标题
BASE_URL	http://localhost	站点访问地址，反代部署时必改；末尾的 / 会被自动去除
HOST	0.0.0.0	服务监听地址
PORT	5000	服务监听端口
SECRET_KEY	CHANGE_ME	Flask 会话密钥，生产环境务必修改
PIDFILE	/tmp/realms-wiki.pid	服务 PID 文件位置，建议改为 /var/run 下
ENV	DEV	设为 DEV 时自动开启 DEBUG、ASSETS_DEBUG 等调试开关

2️⃣ 数据与 Wiki 内容

配置项	默认值	作用
WIKI_PATH	/tmp/wiki	Wiki 数据目录（一个 Git 仓库），内容都存这里
WIKI_HOME	home	首页对应的页面名
DB_URI	sqlite:////tmp/wiki.db	数据库连接串，支持 SQLite / MySQL / MariaDB / PostgreSQL 等 SQLAlchemy 支持的任意数据库
WIKI_LOCKED_PAGES	[]	锁定不可修改的页面名列表

⚠️ 匿名模式或单用户场景可以不配数据库；开启本地账号/注册后建议至少使用独立的 SQLite 文件，生产环境推荐 MySQL 或 PostgreSQL。

3️⃣ 缓存配置

配置项	默认值	作用
CACHE_TYPE	simple	缓存类型：simple / redis / memcached
CACHE_REDIS_HOST	127.0.0.1	Redis 主机
CACHE_REDIS_PORT	6379	Redis 端口
CACHE_REDIS_DB	0	Redis 数据库序号
CACHE_REDIS_PASSWORD	None	Redis 密码
CACHE_MEMCACHED_SERVERS	["127.0.0.1:11211"]	Memcached 服务器列表

4️⃣ 搜索配置

配置项	默认值	作用
SEARCH_TYPE	simple	搜索后端：simple / whoosh / elasticsearch
ELASTICSEARCH_URL	http://127.0.0.1:9200	Elasticsearch 地址
ELASTICSEARCH_FIELDS	["name"]	可搜索字段，可选 name / content / username / message
WHOOSH_INDEX	/tmp/whoosh	Whoosh 索引路径（不存在会自动创建，需可写）
WHOOSH_LANGUAGE	en	Whoosh 语言，建议设为 Wiki 实际语言以启用分词优化

5️⃣ 权限与认证

配置项	默认值	作用
ALLOW_ANON	True	是否允许匿名编辑（实际生效值 = not PRIVATE_WIKI and ALLOW_ANON）
REGISTRATION_ENABLED	True	是否开放用户注册
PRIVATE_WIKI	False	私有 Wiki：开启后匿名者不能访问页面
AUTH_LOCAL_ENABLE	True	本地账号认证开关，设为 false 可禁用
AUTH_PROXY	False	是否信任反向代理/SSO 注入的身份
AUTH_PROXY_HEADER_NAME	REMOTE_USER	代理传递用户名的 HTTP 头名
RECAPTCHA_ENABLE	False	注册时启用 Google ReCAPTCHA
RECAPTCHA_PUBLIC_KEY / RECAPTCHA_PRIVATE_KEY	内置示例值	ReCAPTCHA 密钥，需换成自己的

LDAP 与 OAuth 不是平铺的键，而是两个独立块，只要配置了它们，对应模块（auth.ldap / auth.oauth）就会自动加载：

{
  "LDAP": {
    "URI": "ldap://127.0.0.1:389",
    "BIND_DN": "uid=%(username)s,ou=People,dc=example,dc=com",
    "KEY_MAP": { "username": "cn", "email": "mail" }
  },
  "OAUTH": {
    "google": { "key": "", "secret": "", "domain": "" },
    "github": { "key": "", "secret": "" }
  }
}

• LDAP 支持 direct bind 与 bind by search（USER_SEARCH），也可用 TLS_OPTIONS / START_TLS 启用加密，详见 realms/modules/auth/ldap/；
• OAuth 支持 github、twitter、facebook、google，domain 可选，用于限制 Google 仅允许某 GSuite 域，实现见 realms/modules/auth/oauth/models.py。

6️⃣ 协作与运行时

配置项	默认值	作用
COLLABORATION	togetherjs	多人实时协作模式：None / firepad / togetherjs
FIREBASE_HOSTNAME	None	使用 firepad 协作时必须填写的 Firebase 主机
DATETIME_FORMAT	%b %d, %Y %I:%M %p	页面日期显示格式（strftime 语法）
ROOT_ENDPOINT	wiki.page	根路由指向的视图端点
USE_X_SENDFILE	False	启用 X-Sendfile 由 Nginx 下发静态文件
DEBUG / ASSETS_DEBUG	False	调试开关（ENV=DEV 时自动为 True）
MODULES	["wiki", "search", "auth"]	启用的功能模块，认证模块会按配置自动追加

四、用环境变量覆盖配置（Docker 场景）

配置读取时会扫描所有以 REALMS_ 为前缀的环境变量并去掉前缀（如 REALMS_PORT → PORT），这比修改 json 更方便容器化部署。docker/Dockerfile 就是这一机制的示例：

ENV REALMS_ENV=docker
ENV REALMS_WIKI_PATH=/home/wiki/data/repo
ENV REALMS_DB_URI='sqlite:////home/wiki/data/wiki.db'

配合 docker-compose.yml 中的挂载卷 ./realms-data:/home/wiki/data，即可在不碰配置文件的情况下完成初始化。

五、新手避坑清单 🛠️

1. SECRET_KEY 必须是随机值：向导默认会生成 64 位随机串，切勿保留 CHANGE_ME；
2. WIKI_PATH 不要放 /tmp：/tmp 重启可能清空，建议改为 /var/lib/realms-wiki 这类持久化目录；
3. BASE_URL 结尾不要加 /：虽然程序会自动去除，但规范写法更保险；
4. 改完配置要重启：realms-wiki restart，或 systemd 下 sudo systemctl restart realms-wiki；
5. 模块按需加载：配置了 LDAP、OAUTH 才会启用对应认证模块，AUTH_LOCAL_ENABLE 控制本地账号模块，均无需手动改 MODULES；
6. 生产环境用 Nginx 反代：完整 Nginx / Apache 示例见 README.md 的 "Nginx Setup" 章节。

六、写在最后

掌握 realms-wiki.json 后，你可以把 Realms Wiki 从单机演示快速升级为生产级的团队协作知识库：Git 化的版本历史、多种认证后端、可切换的缓存与搜索引擎，全部通过一份 JSON 文件掌控。先跑通 realms-wiki setup，再按需逐项微调，是部署 Realms Wiki 最快也最稳的路径。

相关源码入口：配置加载逻辑 realms/config/init.py、setup 向导 realms/commands.py、认证模块 realms/modules/auth/、搜索模块 realms/modules/search/。