RhodeCode 4.27.1 配置参数详解

目标：逐段解析 RhodeCode 4.27.1 的配置文件体系——Community 实例的 rhodecode.ini 与 VCSServer 实例的 vcsserver.ini，覆盖 gunicorn 应用服务器、数据库连接、缓存与会话、Celery 任务队列、VCS 接线、SSH/SVN、日志等全部常用参数段；并给出三组「修改参数 → 重启实例 → 验证生效」的实测闭环，讲清每个参数改在哪里、怎么生效、如何验证。安装过程与环境准备见 《RhodeCode 4.27.1 Ubuntu 22.04 安装指南》。

一、环境信息

本篇参数与实测基于以下环境（与安装篇同一台实验机）：

参数溯源说明：本篇所有参数表均取自实验机上由安装器生成的两份配置文件原文（/root/.rccontrol/community-1/rhodecode.ini，818 行；/root/.rccontrol/vcsserver-1/vcsserver.ini，199 行），未做美化；「本机值」列即文件中的实际生效值。配置文件选型与版本背景见 《RhodeCode 介绍与选型指南》。

二、配置文件体系总览

2.1 四个配置文件的分工

rccontrol 安装完成后，配置分散在四个 ini 文件中，层级如下：

⚠️ 注意：gunicorn_conf.py 文件头原文为 "This file is managed by the installer. It shouldn't be modified. If you still wish to make changed create a empty file called gunicorn_conf.py.keep In the same location so installer will not override it on upgrades."——即升级会被覆盖，确需定制时在同目录放一个空的 gunicorn_conf.py.keep 文件阻止覆盖。

2.2 两个特殊变量

• %(here)s：ini 文件所在目录的绝对路径。例如 cache_dir = %(here)s/data 在 community-1 上展开为 /root/.rccontrol/community-1/data。迁移实例目录时用相对写法可以少改配置。
• {ENV_变量名}：app:main 段支持环境变量注入，原文注释示例：sqlalchemy.db1.url = {ENV_RC_DB_URL}——密码不出现在文件里的做法。

2.3 生效机制

所有 [server:main] 与 [app:main] 参数在 gunicorn 启动时读取一次，运行期不热加载；改动后必须重启实例：

# 改 community-1 的参数后
/root/.rccontrol-profile/bin/rccontrol restart community-1
# 改 vcsserver-1 的参数后
/root/.rccontrol-profile/bin/rccontrol restart vcsserver-1

重启动作的逐命令实测与回显见 《RhodeCode 4.27.1 常用 CLI 与运维命令详解》；本篇第十章给出三组「改参数 → restart → 验证」的完整闭环。

三、[server:main]：gunicorn 应用服务器参数

两个实例的 [server:main] 段结构相同，差异在 worker 模型。以下参数对两个实例都有效，表内「本机值」列同时给出 community-1 / vcsserver-1：

配套的 [filter:proxy-prefix] 段（子路径部署用）：

💡 调优点：timeout = 21600（6 小时）看似夸张，实为大仓库 HTTP 协议操作的保护值——clone/push 走的 HTTP 请求周期极长，Nginx 侧的 proxy_read_timeout 需与之对齐（安装篇反代配置取 3600 秒即覆盖大多数场景）。

四、[app:main] 应用核心参数（全局与安全）

4.1 应用身份与全局行为

4.2 大对象与展示

4.3 协议与安全

4.4 管理面限制与许可

五、数据库连接参数（sqlalchemy.db1.*）

⚠️ 注意：连接串中的数据库密码是明文。两个缓解手段：把 url 改成 {ENV_RC_DB_URL} 环境变量注入；对文件收权 chmod 600 /root/.rccontrol/community-1/rhodecode.ini。换数据库密码时同步改此处并 restart（安装篇实测 PostgreSQL SCRAM/MD5 认证兼容问题即发生在这条链路上）。

六、缓存与会话参数

6.1 dogpile 缓存（rc_cache.*）

四个缓存命名空间 + VCSServer 侧一个，本机值如下：

多实例/大规模部署的演进路径（ini 内注释原文即给出模板）：cache_perms 与 cache_repo 可切换 dogpile.cache.rc.redis 后端（带分布式锁），Redis 参数经 rc_cache.*.arguments.host/port/db/socket_timeout/redis_expiration_time/distributed_lock 下发；VCSServer 侧 rc_cache.repo_object 同理（本机为 file_namespace，30 天，Redis 备选后端名为 dogpile.cache.rc.redis_msgpack）。

6.2 beaker 会话（beaker.session.*）

💡 技术拓展：session 存储选型——file 型会话与本地磁盘绑定，多实例负载均衡时无法共享；切 ext:redis 只需 beaker.session.type = ext:redis + beaker.session.url = redis://127.0.0.1:6379/2 两行（注释模板原文），是横向扩展的第一步。

七、异步任务与扩展模块参数

7.1 Celery 任务队列

7.2 全文搜索

7.3 文件存储与实时通道

八、VCS 接线与协议参数

8.1 VCSServer 连接

8.2 Subversion 代理（mod_dav_svn）

8.3 SSH 协议

SSH 模块的启用还依赖系统侧动作（rccontrol enable-module ssh + sshd 配置），完整启用流程见命令篇。

九、日志配置段

rhodecode.ini 尾部是标准 Python logging 配置，三段式（vcsserver.ini 同构，logger 只有 root 与 vcsserver 两项）：

日志落点：gunicorn 的 stdout/stderr 由 supervisord 重定向到 /root/.rccontrol/community-1/community.log 与 /root/.rccontrol/vcsserver-1/vcsserver.log（supervisord.ini 中 stdout_logfile 指定），应用自身不再写独立日志文件——这也是「看日志必须经 supervisord」的原因。

十、参数修改与生效验证（三组实测）

以下三组实验全部在本实验机完成：改参数 → rccontrol restart community-1 → curl 验证 → 改回原值 → 复核 diff 为空。原始输出存档于实验记录（此处回显为照抄）。

10.1 实测一：改监听端口（[server:main] port）

# 1. 修改端口（用编辑器或一行替换均可）
grep -n '^port = ' /root/.rccontrol/community-1/rhodecode.ini
sed -i 's/^port = 10020/port = 10021/' /root/.rccontrol/community-1/rhodecode.ini
grep -n '^port = ' /root/.rccontrol/community-1/rhodecode.ini

# 2. 重启实例
/root/.rccontrol-profile/bin/rccontrol restart community-1

重启与验证回显（实测照抄）：

31:port = 10020
31:port = 10021
Stopping instance: community-1
Starting instance: community-1
--- curl new port 10021:
200
--- curl old port 10020 (expect refused):
000
exit=7 (connection refused)

改回 10020 并 restart 后 restored 10020: 200。结论：监听端口以 rhodecode.ini 的 port = 为准，supervisord.ini 里 _port = 10020 只是安装器写入的记录值，改端口不需要动 supervisord.ini。

10.2 实测二：开启响应压缩（gzip_responses）

sed -i 's/^gzip_responses = false/gzip_responses = true/' /root/.rccontrol/community-1/rhodecode.ini
/root/.rccontrol-profile/bin/rccontrol restart community-1
curl -s -D - -o /dev/null -H 'Accept-Encoding: gzip' http://127.0.0.1:10020/_admin/login

实测回显（响应头）：

HTTP/1.1 200 OK
content-encoding: gzip

结论：gzip_responses 开启后应用层压缩即时生效；上 Nginx 反代后压缩通常交给 Nginx 的 gzip 模块，该参数应保持 false 避免双重压缩。

10.3 实测三：界面语言（lang）

sed -i 's/^lang = en/lang = zh/' /root/.rccontrol/community-1/rhodecode.ini
/root/.rccontrol-profile/bin/rccontrol restart community-1
curl -s http://127.0.0.1:10020/_admin/login | grep -oE '登录|用户名|密码' | sort | uniq -c

实测回显（登录页命中中文文案）：

      1 密码
      2 登录

改回 lang = en 并 restart 后，diff 对原文件校验为空（实测末行回显 INI RESTORED OK），三个参数（port/gzip_responses/lang）全部还原，服务恢复正常（final 10020: 200）。

10.4 生效路径小结

十一、常见配置问题与排查

⚠️ 注意：rccontrol 本身没有开机自启机制（安装篇实测 /etc/init.d 与 systemd 均无），服务器重启后需 systemctl/手工拉起 rccontrol 进程守护，配置篇不再重复，见安装篇第六章的 systemd 单元方案。

十二、参考链接

• 配置参数逐条出处：实验机 /root/.rccontrol/community-1/rhodecode.ini（4.27.1 安装器生成原文，818 行）与 /root/.rccontrol/vcsserver-1/vcsserver.ini（199 行）
• 官方文档站：https://docs.rhodecode.com（Configuration / rhodecode-tools 章节）
• 下载与 MANIFEST：https://dls.rhodecode.com/linux/MANIFEST
• 选型与版本背景：《RhodeCode 介绍与选型指南》
• 安装与排障实录：《RhodeCode 4.27.1 Ubuntu 22.04 安装指南》
• 启停/升级/索引/备份命令实操：《RhodeCode 4.27.1 常用 CLI 与运维命令详解》