Review Board 8.1 配置参数详解
逐项解释 Review Board 8.1 的三层配置体系:settings_local.py 文件层(数据库/缓存/密钥/域名白名单)、站点配置层 91 个键(认证/缓存/邮件/Diff)与 Web 接入层参数,含 rb-site manage 读写实测与 --value false 布尔值陷阱实录。
Review Board 8.1 配置参数详解
目标:逐项解释 Review Board 8.1 的配置体系——
conf/settings_local.py文件层配置(数据库、缓存、密钥、域名白名单等 7 段)与存于数据库的站点配置(siteconfig,实测共 91 个键,覆盖认证、缓存、邮件、Diff 展示等),以及rb-site manage读取/修改站点配置的实测用法与命令行布尔值陷阱。全部键值与回显均来自真实站点(2026-10-28)。安装过程见 《Review Board 8.1 Ubuntu 22.04 安装指南》。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| 服务器 IP | 192.168.1.100(站点域名) |
| Review Board 版本 | 8.1(rb-site 8.1 / Python 3.10.12) |
| 站点目录 | /opt/reviewboard/site |
| 虚拟环境 | /opt/reviewboard/venv |
| 数据库 | MySQL 8.0.46(库名 reviewboard) |
| 缓存 | memcached 1.6.14(127.0.0.1:11211) |
| 管理员账号 | admin / q1w2e3r4 |
文中所有 rb-site manage ... 命令均在站点所在服务器以 root 执行;配置项的默认值均为全新安装后未做过任何修改的实测值。
二、配置体系总览
Review Board 8.1 的配置分三层,各自职责不同:
| 层 | 位置 | 存储 | 职责 |
|---|---|---|---|
| 文件配置层 | /opt/reviewboard/site/conf/settings_local.py | Python 文件 | Django 框架级配置:数据库连接、缓存后端、SECRET_KEY、域名白名单、调试开关等,改动需重启服务 |
| 站点配置层(siteconfig) | 数据库(随站点库一起备份) | 数据库记录 | 业务与管理界面级配置,实测共 91 个键:认证方式、邮件服务器、Diff 展示、搜索开关等,rb-site manage 命令行与管理界面都能改 |
| Web 接入层 | conf/webconfs/ 样例 + /etc/nginx/sites-available/reviewboard、/etc/uwsgi/apps-available/reviewboard.ini | Nginx/uWSGI 配置 | 进程模型、socket、静态文件别名等,见第十章 |
查看文件层全貌(实测回显,SECRET_KEY 出于安全考虑隐去实际值):
# cat /opt/reviewboard/site/conf/settings_local.py
# Site-specific configuration settings for Review Board.
# Definitions for some of these settings can be found at
# https://docs.djangoproject.com/en/dev/ref/settings/
# Database configuration.
DATABASES = {
"default": {
"ENGINE": "django.db.backends.mysql",
"NAME": "reviewboard",
"USER": "reviewboard",
"PASSWORD": "q1w2e3r4",
"HOST": "localhost",
"PORT": ""
}
}
# Cache backend settings.
CACHES = {
"default": {
"BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
"LOCATION": "127.0.0.1:11211"
}
}
# Unique secret key. Don't share this with anybody!
#
# This is used for generating encrypted content, like repository credentials
# and user password hashes, and for your server's Install Key (needed for
# some extensions and for support).
#
# The same key must be used for any server talking to the configured
# database. If you create or move the site, this same key must be used.
SECRET_KEY = "(50 位随机串,向导自动生成,请勿外泄)"
# The path in the URL of the Review Board server, relative to the domain.
SITE_ROOT = "/"
# This should *always* be set to False in production! Only set this to True
# on test servers when requested by Beanbag, Inc. support.
DEBUG = False
# A list of domains or IP addresses that this server identifies as.
# Review Board will refuse to handle requests to anything else.
ALLOWED_HOSTS = [
"192.168.1.100",
"127.0.0.1",
"localhost"
]
# A list of external IP addresses that should be able to access the /health/
# endpoint.
HEALTHCHECK_IPS = []
三、settings_local.py 文件配置详解
3.1 DATABASES——数据库连接
| 键 | 实测值 | 说明 |
|---|---|---|
| ENGINE | django.db.backends.mysql | Django 数据库后端;rb-site install 选 mysql 时生成。改 PostgreSQL 需重装向导或手改并装驱动 |
| NAME | reviewboard | 库名,须与向导回答一致 |
| USER / PASSWORD | reviewboard / q1w2e3r4 | 数据库账号;改密码后要同步改这里并重启服务 |
| HOST | localhost | 独立数据库服务器时填其 IP,并同步放开 MySQL 远程授权 |
| PORT | ""(空) | 空串表示用该数据库默认端口(MySQL 3306) |
3.2 CACHES——缓存后端
| 键 | 实测值 | 说明 |
|---|---|---|
| BACKEND | django.core.cache.backends.memcached.PyMemcacheCache | 向导选 memcached 时生成,驱动为 pymemcache(随包安装的 4.0.0) |
| LOCATION | 127.0.0.1:11211 | memcached 地址;多台用分号分隔 |
缓存断连不会让页面报错,但会导致每个请求都直查数据库,高负载时表现为整体变慢。变更后用 printf "version\r\n" | nc 127.0.0.1 11211 能返回 VERSION 1.6.14 确认缓存可达。
3.3 SECRET_KEY——站点密钥
向导自动生成的 50 位随机串。用途(配置文件注释原文):生成加密内容(仓库凭据、用户口令哈希)与站点的 Install Key;同一数据库的所有服务器必须使用同一个 key,站点迁移时也必须沿用。因此:
- 备份站点目录时必须包含本文件(丢失 = 库中加密数据全部不可解);
- 严禁外泄(注释原文 "Don't share this with anybody!")。
3.4 SITE_ROOT 与 ALLOWED_HOSTS
SITE_ROOT = "/":站点 URL 路径前缀,对应安装时 Root Path 的回答;装在子路径时形如"/reviews/";ALLOWED_HOSTS:域名/IP 白名单,不在列表内的请求一律 400(简短的Bad Request (400)页,DEBUG=False 时无原因说明)。向导只写入 Domain Name 一项,本机验证要手动补127.0.0.1、localhost,复现实录见安装指南排障章。
3.5 DEBUG 与 HEALTHCHECK_IPS
DEBUG = False:配置注释明确要求生产恒为 False,仅官方支持人员要求时才在测试服务器临时开启;HEALTHCHECK_IPS = []:允许访问/health/端点的外部 IP 列表,空列表表示仅本机可访问。负载均衡器做健康检查时把其来源 IP 加进来。
文件层任何改动都要 systemctl restart reviewboard 才生效。
四、站点配置的读取
站点配置层提供三个管理命令(rb-site manage <站点目录> <命令>):
# list-siteconfig:输出全部配置键的 JSON(实测共 91 键,此处节选)
/opt/reviewboard/venv/bin/rb-site manage /opt/reviewboard/site list-siteconfig
{
"auth_backend": "builtin",
"auth_require_sitewide_login": false,
"cache_backend": {
"default": {
"BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
"LOCATION": "localhost:11211"
}
},
"cache_expiration_time": 2592000,
"company": null,
...
}
# get-siteconfig --key:读单个键(实测回显)
# /opt/reviewboard/venv/bin/rb-site manage /opt/reviewboard/site get-siteconfig --key auth_backend
builtin
# /opt/reviewboard/venv/bin/rb-site manage /opt/reviewboard/site get-siteconfig --key cache_expiration_time
2592000
键不存在时报错并退出(实测回显):
CommandError: 'not_exist_key' is not a valid settings key
五、站点配置的修改与布尔值陷阱
5.1 set-siteconfig 基本用法
/opt/reviewboard/venv/bin/rb-site manage /opt/reviewboard/site set-siteconfig \
--key auth_require_sitewide_login --value true
执行时先展示 diff 再要求确认(实测回显):
The following changes will be made:
--- settings
+++ settings
@@ -23,7 +23,7 @@
"auth_ldap_uid_mask": "",
"auth_ldap_uri": "",
"auth_nis_email_domain": "",
- "auth_require_sitewide_login": false,
+ "auth_require_sitewide_login": true,
"auth_x509_autocreate_users": false,
"auth_x509_custom_username_field": null,
"auth_x509_username_field": "SSL_CLIENT_S_DN_CN",
The changes have been saved.
确认前先用 --dry-run 预览(diff 相同,结尾为 No changes have been saved.);脚本化调用加 -y 跳过确认。
5.2 ⚠️ 布尔值陷阱:--value false 实际是 true
实测发现:--value 接收的一切输入都按字符串处理,而 Python 里非空字符串恒为真值。因此 --value false 与 --value true 产生完全相同的 diff(均把目标改成 true):
# set-siteconfig --key auth_require_sitewide_login --value false --dry-run 的 diff
- "auth_require_sitewide_login": false,
+ "auth_require_sitewide_login": true,
更隐蔽的是后续想改回时,--value false 计算出的新值(true)与现值(true)相同,命令直接返回 No settings were changed.——配置被卡在 true 上无法用 --value 改回。
正确姿势:布尔、null、数字、列表等非字符串值一律用 --json-merge-patch(RFC 7396),JSON 解析器会保留真实类型(实测回显):
# /opt/reviewboard/venv/bin/rb-site manage /opt/reviewboard/site set-siteconfig \
--json-merge-patch '{"auth_require_sitewide_login": false}' -y
The following changes will be made:
--- settings
+++ settings
@@ -23,7 +23,7 @@
"auth_ldap_uid_mask": "",
"auth_ldap_uri": "",
"auth_nis_email_domain": "",
- "auth_require_sitewide_login": true,
+ "auth_require_sitewide_login": false,
"auth_x509_autocreate_users": false,
"auth_x509_custom_username_field": null,
"auth_x509_username_field": "SSL_CLIENT_S_DN_CN",
The changes have been saved.
# get-siteconfig --key auth_require_sitewide_login
false
复杂批量变更还支持 --json-patch(RFC 6902,JSON Patch);两者都可用 --json-*-patch=- 从标准输入读入。嵌套键用点号定位,例如 --key cache_backend.default.LOCATION。
5.3 修改的生效方式
站点配置保存在数据库中,get-siteconfig/list-siteconfig 立即可读到新值;Web 进程内的配置缓存则以服务重启为准,生产变更后建议 systemctl restart reviewboard 确保全量生效。
六、认证配置项详解
认证配置以 auth_ 为前缀,实测键值如下(全新安装默认值):
| 键 | 默认值 | 说明 |
|---|---|---|
| auth_backend | builtin | 认证后端。builtin=本地账号;LDAP/AD 等需安装扩展后改此项 |
| auth_require_sitewide_login | false | 是否全站强制登录(true 时未登录用户看任何页面都要先登录,内网评审系统常开此项) |
| auth_ldap_uri | "" | LDAP 服务器 URI(ldap:// 或 ldaps://) |
| auth_ldap_base_dn | null | 检索起点 DN,如 dc=example,dc=com |
| auth_ldap_uid | uid | 用户名属性字段 |
| auth_ldap_uid_mask | "" | uid 匹配掩码 |
| auth_ldap_tls | false | 是否启用 STARTTLS |
| auth_ldap_email_domain | "" | 账号无邮箱属性时的补全域名 |
| auth_ldap_email_attribute / full_name_attribute / given_name_attribute / surname_attribute | null | 邮箱/全名/名/姓的属性名 |
| auth_ldap_anon_bind_uid / auth_ldap_anon_bind_passwd | "" / "" | 匿名绑定凭据 |
| auth_ad_domain_controller / auth_ad_domain_name / auth_ad_find_dc_from_dns / auth_ad_group_name / auth_ad_ou_name / auth_ad_recursion_depth / auth_ad_search_root / auth_ad_use_tls | null | Active Directory 认证相关(需 Active Directory 扩展) |
| auth_nis_email_domain | "" | NIS 认证的邮箱补全域 |
| auth_digest_file_location / auth_digest_realm | null / null | HTTP Digest 认证文件与域 |
| auth_x509_username_field | SSL_CLIENT_S_DN_CN | X.509 客户端证书取用户名的字段 |
| auth_x509_custom_username_field / auth_x509_username_regex | null / "" | 自定义证书字段与正则 |
| auth_x509_autocreate_users | false | 证书登录时是否自动建号 |
LDAP 接入的完整改法:先安装认证扩展,再按上表改 auth_ldap_* 系列,最后把 auth_backend 切到对应后端。注意第六章陷阱:auth_ldap_tls 这类布尔项必须走 --json-merge-patch。
七、缓存与搜索配置项详解
| 键 | 默认值 | 说明 |
|---|---|---|
| cache_backend | {"default": {"BACKEND": "...PyMemcacheCache", "LOCATION": "localhost:11211"}} | 站点配置层也存一份缓存后端描述;与 settings_local.py 的 CACHES 保持一致即可 |
| cache_expiration_time | 2592000 | 缓存过期时间,单位秒(2592000 = 30 天) |
| search_enable | false | 全文搜索开关(Whoosh 索引已随包内置,开启前先建索引) |
| search_index_file | null | 索引文件路径;null 时用站点目录默认位置 |
search_enable 是布尔项,开启必须用 --json-merge-patch '{"search_enable": true}'(原因见 5.2),随后建立索引并按安装指南第十章的 cron.conf 说明让 update_index 每 10 分钟增量更新。
八、邮件与站点信息配置项详解
| 键 | 默认值 | 说明 |
|---|---|---|
| mail_host | localhost | SMTP 服务器地址 |
| mail_port | 25 | SMTP 端口 |
| mail_host_user / mail_host_password | "" / "" | SMTP 认证账号(不需要认证则留空) |
| mail_use_tls | false | 是否启用 STARTTLS |
| mail_default_from | noreply@192.168.1.100 | 通知邮件发件人(默认按站点域名拼出) |
| mail_server_address | root@localhost | 管理员收件地址(错误报告发往这里) |
| mail_send_review_mail | false | 是否实际发出评审邮件通知;false 时只入队不投递 |
| site_admin_name / site_admin_email | admin / admin@example.com | 站点管理员姓名与邮箱(安装向导的回答) |
| site_domain_method | http | 站点对外 URL 协议;上 HTTPS 后改为 https |
| company | null | 组织名(向导回答 Example Inc 存于站点记录) |
邮件连通性验证思路:先 mail_send_review_mail 与 SMTP 信息配好(布尔项走 merge-patch),再发起一条评论触发通知,观察站点日志中的投递记录。SMTP 服务不可达时任务队列会重试并在日志中报连接错误。
九、Diff 展示与上传配置项详解
| 键 | 默认值 | 说明 |
|---|---|---|
| diffviewer_context_num_lines | 5 | 展开 diff 上下文时额外显示的行数 |
| diffviewer_paginate_by | 20 | Diff 页每页文件数 |
| diffviewer_paginate_orphans | 10 | 尾页不足该行数时并入上一页 |
| diffviewer_syntax_highlighting | true | 是否启用语法高亮 |
| diffviewer_include_space_patterns | [] | 始终保留空白的文件匹配模式列表 |
| site_upload_max_memory_size | 2621440 | 上传内容进内存的阈值(字节,2.5MB),超出转临时文件 |
| site_upload_temp_dir | null | 上传临时目录;null 用系统默认 |
| site_media_root / site_static_root | /opt/reviewboard/site/htdocs/media、/opt/reviewboard/site/htdocs/static | 媒体与静态文件根目录(Nginx alias 指向这里) |
| site_media_url / site_static_url | /media/、/static/ | 对应 URL 前缀 |
排查超大 diff 导致页面慢时可配合 find-large-diffs 扫描命令(交互确认后输出 CSV,含 Max Files / Max Diff Size 等指标),用法与回显见 《Review Board 8.1 常用 CLI 与运维命令详解》。
十、Web 接入层关键参数
站点目录 conf/webconfs/ 里有向导生成的各 Web 服务器样例(apache-wsgi.conf、nginx-to-gunicorn.conf、nginx-to-uwsgi.conf、uwsgi.ini、run-gunicorn.sh),最终落地的是两个系统配置。逐参数解释(与安装指南的配置全文对应):
/etc/uwsgi/apps-available/reviewboard.ini:
| 参数 | 值 | 说明 |
|---|---|---|
| plugins | python3 | Debian 版 uWSGI 按插件加载语言运行时,缺这行无法启动 |
| module | reviewboard.wsgi:application | WSGI 入口 |
| env | REVIEWBOARD_SITEDIR=/opt/reviewboard/site | 站点定位环境变量,缺失即启动失败 |
| chdir | /opt/reviewboard/site | 进程工作目录 |
| processes / threads | 6 / 30 | 工作进程与每进程线程数;并发上调时同步评估内存(每进程约 30MB 起步) |
| socket | /opt/reviewboard/site/data/uwsgi.sock | 与 Nginx 之间的 Unix socket |
| chmod-socket / chown-socket | 660 / www-data:www-data | socket 权限,保证 Nginx(www-data)可读写 |
| virtualenv | /opt/reviewboard/site/venv | 自动激活的虚拟环境 |
| vacuum / die-on-term | true / true | 退出时清理 socket;按 systemd 语义响应 SIGTERM |
/etc/nginx/sites-available/reviewboard:
| 参数 | 值 | 说明 |
|---|---|---|
| listen | 8141(IPv4 + IPv6) | Web 端口,改端口需同步改 ALLOWED_HOSTS 叙述中的访问地址 |
| server_name | 192.168.1.100 | 与 ALLOWED_HOSTS 对应 |
| location / | uwsgi_pass unix:...uwsgi.sock | 动态请求转发给 uWSGI |
| location /media/、/static/ | alias 到 htdocs 对应目录 | 静态资源由 Nginx 直出(expires max + Cache-Control public) |
| access_log / error_log | 站点 logs/ 下 | Nginx 层日志,与应用日志分列 |
/etc/systemd/system/reviewboard.service:User=www-data(与属主修正配套)、Restart=on-failure + RestartSec=5(异常自愈)、After/Wants mysql+memcached(依赖顺序)。服务单元与启动实录见安装指南第九章。
十一、常见配置问题与排障
11.1 改配置后访问仍 400
ALLOWED_HOSTS 属文件层配置,改完必须 systemctl restart reviewboard;同时确认访问所用的 Host 头(IP 或域名)确实在列表内。
11.2 --value false 后配置不生效且改不回
第五章实测的布尔值陷阱:--value 把输入当字符串,"false" 恒为真值,且重复执行返回 No settings were changed.。一律改用 --json-merge-patch '{"键": false}' 修复。
11.3 get-siteconfig 报 key 无效
CommandError: 'not_exist_key' is not a valid settings key
先用 list-siteconfig | grep 关键词 确认键的真实拼写(如 diff 相关键前缀是 diffviewer_ 而非 diff_)。
11.4 想改的键在站点配置里找不到
站点配置只收业务键(91 个);数据库连接、SECRET_KEY、DEBUG 这类框架键在 settings_local.py 文件层,改文件并重启。两层职责划分见第二章对照表。
11.5 配置备份要点
- 文件层:备份整个
conf/目录(含 settings_local.py 与 webconfs/); - 站点配置层:随数据库一起走(存于站点库),按安装指南的数据库备份流程覆盖;
- 两层缺一不可,只备文件层会丢 91 个业务键的改动。
十二、参考链接
- 官方管理手册(Administration Settings):https://www.reviewboard.org/docs/manual/8.1/admin/configuration/
- Djblets siteconfig 机制说明:https://djblets.readthedocs.io/
- RFC 7396(JSON Merge Patch):https://datatracker.ietf.org/doc/html/rfc7396
- RFC 6902(JSON Patch):https://jsonpatch.com/
本系列其余篇目:组件定位与同类对比见 《Review Board 介绍与选型指南》;安装全流程实测见 《Review Board 8.1 Ubuntu 22.04 安装指南》;
rb-site全家桶与备份升级实操见 《Review Board 8.1 常用 CLI 与运维命令详解》。