Review Board 8.1 配置参数详解

逐项解释 Review Board 8.1 的三层配置体系:settings_local.py 文件层(数据库/缓存/密钥/域名白名单)、站点配置层 91 个键(认证/缓存/邮件/Diff)与 Web 接入层参数,含 rb-site manage 读写实测与 --value false 布尔值陷阱实录。

Review BoardReview Board代码审查Python 编程DevOps工程2026/10/28

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
服务器 IP192.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.pyPython 文件Django 框架级配置:数据库连接、缓存后端、SECRET_KEY、域名白名单、调试开关等,改动需重启服务
站点配置层(siteconfig)数据库(随站点库一起备份)数据库记录业务与管理界面级配置,实测共 91 个键:认证方式、邮件服务器、Diff 展示、搜索开关等,rb-site manage 命令行与管理界面都能改
Web 接入层conf/webconfs/ 样例 + /etc/nginx/sites-available/reviewboard、/etc/uwsgi/apps-available/reviewboard.iniNginx/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——数据库连接

键实测值说明
ENGINEdjango.db.backends.mysqlDjango 数据库后端;rb-site install 选 mysql 时生成。改 PostgreSQL 需重装向导或手改并装驱动
NAMEreviewboard库名,须与向导回答一致
USER / PASSWORDreviewboard / q1w2e3r4数据库账号;改密码后要同步改这里并重启服务
HOSTlocalhost独立数据库服务器时填其 IP,并同步放开 MySQL 远程授权
PORT""(空)空串表示用该数据库默认端口(MySQL 3306)

3.2 CACHES——缓存后端

键实测值说明
BACKENDdjango.core.cache.backends.memcached.PyMemcacheCache向导选 memcached 时生成,驱动为 pymemcache(随包安装的 4.0.0)
LOCATION127.0.0.1:11211memcached 地址;多台用分号分隔

缓存断连不会让页面报错,但会导致每个请求都直查数据库,高负载时表现为整体变慢。变更后用 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_backendbuiltin认证后端。builtin=本地账号;LDAP/AD 等需安装扩展后改此项
auth_require_sitewide_loginfalse是否全站强制登录(true 时未登录用户看任何页面都要先登录,内网评审系统常开此项)
auth_ldap_uri""LDAP 服务器 URI(ldap:// 或 ldaps://)
auth_ldap_base_dnnull检索起点 DN,如 dc=example,dc=com
auth_ldap_uiduid用户名属性字段
auth_ldap_uid_mask""uid 匹配掩码
auth_ldap_tlsfalse是否启用 STARTTLS
auth_ldap_email_domain""账号无邮箱属性时的补全域名
auth_ldap_email_attribute / full_name_attribute / given_name_attribute / surname_attributenull邮箱/全名/名/姓的属性名
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_tlsnullActive Directory 认证相关(需 Active Directory 扩展)
auth_nis_email_domain""NIS 认证的邮箱补全域
auth_digest_file_location / auth_digest_realmnull / nullHTTP Digest 认证文件与域
auth_x509_username_fieldSSL_CLIENT_S_DN_CNX.509 客户端证书取用户名的字段
auth_x509_custom_username_field / auth_x509_username_regexnull / ""自定义证书字段与正则
auth_x509_autocreate_usersfalse证书登录时是否自动建号

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_time2592000缓存过期时间,单位秒(2592000 = 30 天)
search_enablefalse全文搜索开关(Whoosh 索引已随包内置,开启前先建索引)
search_index_filenull索引文件路径;null 时用站点目录默认位置

search_enable 是布尔项,开启必须用 --json-merge-patch '{"search_enable": true}'(原因见 5.2),随后建立索引并按安装指南第十章的 cron.conf 说明让 update_index 每 10 分钟增量更新。

八、邮件与站点信息配置项详解

键默认值说明
mail_hostlocalhostSMTP 服务器地址
mail_port25SMTP 端口
mail_host_user / mail_host_password"" / ""SMTP 认证账号(不需要认证则留空)
mail_use_tlsfalse是否启用 STARTTLS
mail_default_fromnoreply@192.168.1.100通知邮件发件人(默认按站点域名拼出)
mail_server_addressroot@localhost管理员收件地址(错误报告发往这里)
mail_send_review_mailfalse是否实际发出评审邮件通知;false 时只入队不投递
site_admin_name / site_admin_emailadmin / admin@example.com站点管理员姓名与邮箱(安装向导的回答)
site_domain_methodhttp站点对外 URL 协议;上 HTTPS 后改为 https
companynull组织名(向导回答 Example Inc 存于站点记录)

邮件连通性验证思路:先 mail_send_review_mail 与 SMTP 信息配好(布尔项走 merge-patch),再发起一条评论触发通知,观察站点日志中的投递记录。SMTP 服务不可达时任务队列会重试并在日志中报连接错误。

九、Diff 展示与上传配置项详解

键默认值说明
diffviewer_context_num_lines5展开 diff 上下文时额外显示的行数
diffviewer_paginate_by20Diff 页每页文件数
diffviewer_paginate_orphans10尾页不足该行数时并入上一页
diffviewer_syntax_highlightingtrue是否启用语法高亮
diffviewer_include_space_patterns[]始终保留空白的文件匹配模式列表
site_upload_max_memory_size2621440上传内容进内存的阈值(字节,2.5MB),超出转临时文件
site_upload_temp_dirnull上传临时目录;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:

参数值说明
pluginspython3Debian 版 uWSGI 按插件加载语言运行时,缺这行无法启动
modulereviewboard.wsgi:applicationWSGI 入口
envREVIEWBOARD_SITEDIR=/opt/reviewboard/site站点定位环境变量,缺失即启动失败
chdir/opt/reviewboard/site进程工作目录
processes / threads6 / 30工作进程与每进程线程数;并发上调时同步评估内存(每进程约 30MB 起步)
socket/opt/reviewboard/site/data/uwsgi.sock与 Nginx 之间的 Unix socket
chmod-socket / chown-socket660 / www-data:www-datasocket 权限,保证 Nginx(www-data)可读写
virtualenv/opt/reviewboard/site/venv自动激活的虚拟环境
vacuum / die-on-termtrue / true退出时清理 socket;按 systemd 语义响应 SIGTERM

/etc/nginx/sites-available/reviewboard:

参数值说明
listen8141(IPv4 + IPv6)Web 端口,改端口需同步改 ALLOWED_HOSTS 叙述中的访问地址
server_name192.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 个业务键的改动。

十二、参考链接


本系列其余篇目:组件定位与同类对比见 《Review Board 介绍与选型指南》;安装全流程实测见 《Review Board 8.1 Ubuntu 22.04 安装指南》;rb-site 全家桶与备份升级实操见 《Review Board 8.1 常用 CLI 与运维命令详解》。