RhodeCode 4.27.1 Ubuntu 22.04 安装指南

在 Ubuntu 22.04.5 LTS 上安装 RhodeCode 4.27.1 的完整实录:rccontrol 在线安装(含 get_rccontrol 502 排障与官方 MANIFEST 离线等效安装)、VCSServer 与 Community 双实例交互向导、systemd 开机自启与 Nginx 反向代理闭环、常见故障排查与卸载清理;全部命令与输出均实测照抄。

RhodeCode版本控制Python 编程Mercurial2026/10/28

RhodeCode 4.27.1 Ubuntu 22.04 安装指南

目标:在 Ubuntu 22.04.5 LTS 服务器上从零安装 RhodeCode Community 4.27.1(rccontrol 原生安装通道),覆盖 PostgreSQL 数据库准备、控制端与两个实例(VCSServer + Community)的完整安装、systemd 开机自启托管、Nginx 反向代理接入与端到端验证;全部命令与回显均在 Ubuntu 22.04.5 LTS 实测,排障实录完整沉淀。

一、环境信息

本指南实测环境与产物布局如下:

项值说明
操作系统Ubuntu 22.04.5 LTS(x86_64)内核 5.15 系列
RhodeCode Community4.27.1(build20221012_1600)Web 应用实例 community-1
RhodeCode VCSServer4.27.1(build20221012_1600)版本库操作实例 vcsserver-1
rccontrol1.24.4官方安装与实例管理工具,自带 Python 2.7.15 运行时
应用服务器gunicorn/19.9.0Community 用 gevent worker,VCSServer 用 sync worker
数据库PostgreSQL 14.24(系统包)systemd 托管,库名/用户名 rhodecode
反向代理Nginx 1.18.0(Ubuntu 包)可选接入层
Git 客户端2.34.1端到端 clone/push 验证用
Community 端口10020(0.0.0.0)Web 与 HTTP(S) 协议入口
VCSServer 端口10010(127.0.0.1)仅本机,Community 内部接线
Supervisor 端口10000(127.0.0.1)rccontrol 进程守护的内部控制口
PostgreSQL 端口5432本机
Nginx 端口8080(示例)反代 10020

目录布局(rccontrol 默认值,本文全程沿用):

  • /opt/rhodecode/:rccontrol 应用商店(store),存放解压后的运行时与应用;
  • /root/.rccontrol-profile/bin/:控制端可执行入口(rccontrol、supervisord、supervisorctl);
  • /root/.rccontrol/:实例目录(community-1、vcsserver-1)、supervisor 配置、下载缓存 cache/;
  • /root/.rccontrol.ini:rccontrol 全局配置(实例开机行为等);
  • /var/opt/rhodecode/repos/:版本库与 Gist 存储根目录(安装时自定)。

💡 说明:rccontrol 以「执行安装的用户家目录」为实例根,本文以 root 安装(实例落在 /root/.rccontrol/);如以普通用户安装,路径中的 /root 会替换为该用户家目录,其余步骤一致。

二、前置条件

2.1 系统依赖

rccontrol 自带全部运行时(连 Python、gunicorn、supervisor 都在应用商店内),系统侧依赖很少,但 tar 包为 bzip2 压缩,最小化安装的系统需要先补齐:

apt update
apt install -y curl wget bzip2 openssh-client

bzip2 缺失会在解压控制端时报错,实测排障见第八章 Q2。Git 客户端(apt install -y git)建议随后一并安装,用于安装完成后的端到端推拉验证。

2.2 PostgreSQL 安装与建库

安装向导支持 SQLite/MySQL/PostgreSQL 三种数据库(官方向导提示:SQLite 仅适合 3-4 用户的小环境或测试,生产推荐 MySQL 或 PostgreSQL)。本文选 PostgreSQL:

apt install -y postgresql

安装后 PostgreSQL 14 由 systemd 托管,创建专用数据库与账号(密码用演示口令 q1w2e3r4):

sudo -u postgres psql
CREATE USER rhodecode WITH PASSWORD 'q1w2e3r4';
CREATE DATABASE rhodecode OWNER rhodecode;
\q

⚠️ 注意:RhodeCode 4.27.1 自带的 psycopg2 2.8.4 编译期 libpq 低于 10,不支持 PostgreSQL 14 默认的 SCRAM-SHA-256 认证;装完必须按第八章 Q4 把该账号的密码改回 md5 方式,否则安装向导初始化数据库时直接报错。

2.3 版本选型说明

RhodeCode 的版本通道需先分清(选择依据详见《RhodeCode 介绍与选型指南》第七章):

通道最高版本形态本文选择
5.x 一体化套件 / Helm Chart5.15.0(2026-10-21)官方 rcstack 套件或 Helm否
rccontrol 原生安装4.27.1系统原生目录 + supervisor 托管是

官方下载清单(MANIFEST,2026-10-28 实抓)中原生通道仅有 4.x 条目,最高即 4.27.1,关键三个包:

包下载地址(https://dls.rhodecode.com/linux/)md5
Control 1.24.4 x86_64RhodeCodeControl-1.24.4+x86_64-linux_build20221012_1600.tar.bz2dac4e22ccfc15a8c533d7625505bf4d6
VCSServer 4.27.1 x86_64RhodeCodeVCSServer-4.27.1+x86_64-linux_build20221012_1600.tar.bz259dfd1d4dba1c161bd61f9d225eafd73
Community 4.27.1 x86_64RhodeCodeCommunity-4.27.1+x86_64-linux_build20221012_1600.tar.bz2148e89d1c2d4fb791d3fd5c19e459a71

关键差异解读:Control 是安装器本体(约百 MB 级),VCSServer 与 Community 是两个运行时包(各 150+ MB,解压后 GB 级);三者均自带运行时依赖,无需额外编译环境。

三、方案 A:rccontrol 在线安装(实测主方案)

3.1 方案说明

rccontrol 官方设计的一键安装路径是:引导脚本装 Control → rccontrol self-init 初始化守护进程 → rccontrol install 先装 VCSServer 再装 Community,两个实例均由 supervisor 托管。本文实测时官方引导脚本服务端异常(见 Q1),改用 MANIFEST 直取 tar 包的等效安装法安装 Control,后续步骤与官方路径完全一致——这也是掌握 rccontrol 目录模型的最好方式。

3.2 安装 rccontrol 控制端

第一步下载官方清单并挑选 Control 包:

cd /root
curl -sS https://dls.rhodecode.com/linux/MANIFEST -o MANIFEST
grep Control MANIFEST

输出(实测,2026-10-28):

dac4e22ccfc15a8c533d7625505bf4d6 https://dls.rhodecode.com/linux/RhodeCodeControl-1.24.4+x86_64-linux_build20221012_1600.tar.bz2
aa297320e0560c9c7b95ed7e78697ece https://dls.rhodecode.com/linux/RhodeCodeControl-1.24.4+i686-linux_build20221012_1600.tar.bz2

第二步下载 x86_64 包并校验 md5:

curl -L -O https://dls.rhodecode.com/linux/RhodeCodeControl-1.24.4+x86_64-linux_build20221012_1600.tar.bz2
md5sum RhodeCodeControl-1.24.4+x86_64-linux_build20221012_1600.tar.bz2

md5sum 输出应等于 MANIFEST 中的 dac4e22ccfc15a8c533d7625505bf4d6(实测一致)。

第三步解压到应用商店并链接控制端入口:

mkdir -p /opt/rhodecode/store
tar xjf RhodeCodeControl-1.24.4+x86_64-linux_build20221012_1600.tar.bz2 -C /opt/rhodecode/store/
ls /opt/rhodecode/store/ | grep control

输出(实测):

xhllvj4dx4avg6ilvcmsnhnvb4ma2y0m-python2.7-rhodecode-control-1.24.4

应用商店条目名是「随机哈希-运行时-应用-版本」格式,把 bin 下三个入口链接到固定 profile 目录:

mkdir -p /root/.rccontrol-profile/bin
ln -s /opt/rhodecode/store/xhllvj4dx4avg6ilvcmsnhnvb4ma2y0m-python2.7-rhodecode-control-1.24.4/bin/rccontrol /root/.rccontrol-profile/bin/rccontrol
ln -s /opt/rhodecode/store/xhllvj4dx4avg6ilvcmsnhnvb4ma2y0m-python2.7-rhodecode-control-1.24.4/bin/supervisord /root/.rccontrol-profile/bin/supervisord
ln -s /opt/rhodecode/store/xhllvj4dx4avg6ilvcmsnhnvb4ma2y0m-python2.7-rhodecode-control-1.24.4/bin/supervisorctl /root/.rccontrol-profile/bin/supervisorctl
export PATH=/root/.rccontrol-profile/bin:$PATH
rccontrol license

输出(实测):

RhodeCode Control 1.24.4 License:
License Type:   Default
Valid:          True
Expiry:         Never
Instances:      Unlimited

⚠️ 注意:export PATH 只对当前会话生效,建议写入 /root/.bashrc;后文所有 rccontrol/supervisorctl 命令均假定该 PATH 已生效。

第四步初始化 rccontrol 与进程守护:

rccontrol self-init

该命令会创建 /root/.rccontrol/ 目录结构(supervisor 配置、cache 缓存等)并启动守护进程 supervisord。

⚠️ 注意:本次实测未留存该步完整回显,预期结果为 rccontrol 配置文件与 supervisor 配置落位、/root/.rccontrol/supervisor/supervisord.log 开始记录、无报错退出;可用 ps -ef | grep supervisord 确认守护进程已在运行(实测其命令行为 .supervisord-wrapped -c /root/.rccontrol/supervisor/supervisord.ini)。

3.3 安装 VCSServer 实例

VCSServer 是版本库操作服务,必须先于 Community 安装。安装命令(交互向导,加 --version 钉版本):

rccontrol install VCSServer --version 4.27.1

全程输出(实测,交互逐行照抄):

Updating MANIFEST file with latest version from https://dls.rhodecode.com/linux/MANIFEST
About to install `vcsserver-1` instance with version: 4.27.1.


Default IP Address to run this instance.
This IP should never be other than 127.0.0.1 unless behind some added authentication.
This can be changed inside /root/.rccontrol/vcsserver-1/vcsserver.ini config later by modifying `host =` parameter.
IP to start the server on [127.0.0.1]: 127.0.0.1
127.0.0.1

Default port to start the instance.
This can be changed inside /root/.rccontrol/vcsserver-1/vcsserver.ini config later by modifying `port =` parameter.
Port for the server to start [10010]:

Creating new instance: vcsserver-1
Installing RhodeCode VCSServer
Downloading https://dls.rhodecode.com/linux/RhodeCodeVCSServer-4.27.1+x86_64-linux_build20221012_1600.tar.bz2 ...
Extracting VCSServer ...
Configuring RhodeCode VCS Server ...
Saving accepted license locally under /root/.rccontrol/vcsserver-1
Supervisord state is: RUNNING
Added process group vcsserver-1

要点:VCSServer 的 IP 官方明确要求保持 127.0.0.1(除非另加认证层),端口默认 10010,直接回车即可;安装完成即已由 supervisor 托管(Added process group vcsserver-1)。

3.4 安装 Community 实例

rccontrol install community --version 4.27.1

💡 说明:install 支持在实例名后直接附加参数(email=、username=、password=、host=、repo_dir= 等,见 rccontrol install --help 的 [PARAMS]...),实测可减少部分交互应答,但端口、数据库类型等仍会进入向导;本文按完整交互流程记录,与读者实际操作一屏一屏对应。

全程交互输出(实测,输出节选——实测首尾,中段为数据库初始化的逐表 SQL 日志,约 1700 行,结构相同不逐行列):

Updating MANIFEST file with latest version from https://dls.rhodecode.com/linux/MANIFEST
About to install `community-1` instance with version: 4.27.1.


First super-admin username.
Use this username for first log-in to RhodeCode Application.
Username [admin]: admin
admin

Initial password for super-admin.
You can always change it after logging in.
Password (min 6 chars): q1w2e3r4

Repeat for confirmation: q1w2e3r4


Email for super-admin. Important notifications are
sent to that email. It can be changed later at any time.
Email: admin@rhodecode.local
admin@rhodecode.local

Path to store the RhodeCode repositories, and repository groups.
If existing path is given RhodeCode can import repositories from it.
This path is also used to store Gists. It can be changed later in admin interface.
Make sure this path is writable by RhodeCode.
Repositories location [/root/repos]: /var/opt/rhodecode/repos
/var/opt/rhodecode/repos

Default IP Address to run this instance.
Default [127.0.0.1] should be used together with http proxy such as Apache or Nginx.
Use 0.0.0.0 to allow access via this server IP directly.
This can be changed inside /root/.rccontrol/community-1/rhodecode.ini config later by modifying `host =` parameter.
IP to start the RhodeCode Community server on [127.0.0.1]: 0.0.0.0
0.0.0.0

Default port to start the instance.
This can be changed inside /root/.rccontrol/community-1/rhodecode.ini config later by modifying `port =` parameter.
Port for the RhodeCode Community server to use [10020]:


Choose database type for new installation.
SQLite should be used in small environments (3-4 users), or for testing purposes.
Choose MySQL or PostgreSQL for optimal performance.
To use MySQL/PostgreSQL you need to create a new database before continuing.
Make sure this host can connect to your Database server.
Database connection details are saved under `sqlalchemy.db1.url =` variable inside /root/.rccontrol/community-1/rhodecode.ini.
Database type - [s]qlite, [m]ysql, [p]ostresql:
pPostgreSQL selected
Database host [127.0.0.1]: 127.0.0.1
127.0.0.1
Database port [5432]: 5432
5432
Database username: rhodecode
rhodecode
Database password: q1w2e3r4

Repeat for confirmation: q1w2e3r4

Database name: rhodecode
rhodecode
Creating new instance: community-1
Installing RhodeCode Community
Downloading https://dls.rhodecode.com/linux/RhodeCodeCommunity-4.27.1+x86_64-linux_build20221012_1600.tar.bz2 ...
Extracting Community ...
Configuring RhodeCode Community ...
2026-10-28 00:47:55.539 [7468] INFO  [rhodecode.model] RhodeCode 4.27.1 initializing db for postgresql://rhodecode:XXXXX@127.0.0.1:5432/rhodecode
2026-10-28 00:47:55.540 [7468] INFO  [rhodecode.lib.db_manage] Existing database with the same name is going to be destroyed.
2026-10-28 00:47:55.540 [7468] INFO  [rhodecode.lib.db_manage] Setup command will run DROP ALL command on that database.
2026-10-28 00:47:55,546 INFO sqlalchemy.engine.base.Engine select version()
…(输出节选——实测首尾:中段为逐表检查与建表的 SQLAlchemy 日志,共约 1700 行)…
2026-10-28 00:47:58,666 INFO sqlalchemy.engine.base.Engine ROLLBACK
2026-10-28 00:47:58.666 [7468] INFO  [rhodecode.config.middleware] Pyramid app `pyramid_app_with_cleanup` created and configured in 1.55s
()
***********************************************************
SUCCESSFULLY INITIALIZED DATABASE, SCHEMA AND DEFAULT DATA.
***********************************************************
2026-10-28 00:47:58.667 [7468] INFO  [rhodecode.lib.rc_cache.cache_key_meta] Clearing 0 cache keys
Configuration of RhodeCode Community passed.
Saving accepted license locally under /root/.rccontrol/community-1
Supervisord state is: RUNNING
Added process group community-1

交互要点逐项说明:

  1. 超级管理员:用户名默认 admin、密码至少 6 位(本文用演示口令 q1w2e3r4)、邮箱用于通知,均可在登录后修改;
  2. 仓库位置:默认 /root/repos,本文改为 /var/opt/rhodecode/repos——该目录同时存放 Gist,生产建议独立数据盘;
  3. 监听 IP:默认 127.0.0.1(配合 Nginx/Apache 反代),本文选 0.0.0.0 便于直连验证,生产接反代时改回;
  4. 端口:默认 10020,直接回车;
  5. 数据库:输入 p 选 PostgreSQL(提示原文如此——[p]ostresql 为向导笔误),随后依次应答 host/port/用户名/密码/库名,与 2.2 节创建的一致;
  6. 初始化:向导会对目标库执行 DROP ALL 后重建 schema(如库名已被占用会提示销毁重建),最后 SUCCESSFULLY INITIALIZED DATABASE, SCHEMA AND DEFAULT DATA. 即成功标志。

3.5 安装验证

第一层:实例状态:

rccontrol status

输出(实测):

RHODECODE CONTROL VERSION: 1.24.4

 - NAME: community-1
 - STATUS: RUNNING
   logs: /root/.rccontrol/community-1/community.log
 - VERSION: 4.27.1 Community
 - VCS: vcsserver-1
 - URL: http://0.0.0.0:10020
 - CONFIG: /root/.rccontrol/community-1/rhodecode.ini

 - NAME: vcsserver-1
 - STATUS: RUNNING
   logs: /root/.rccontrol/vcsserver-1/vcsserver.log
 - VERSION: 4.27.1 VCSServer
 - URL: http://127.0.0.1:10010
 - CONFIG: /root/.rccontrol/vcsserver-1/vcsserver.ini

第二层:HTTP 探活:

curl -sSI http://127.0.0.1:10020/ | head -8

输出(实测):

HTTP/1.1 200 OK
Server: gunicorn/19.9.0
Date: Wed, 28 Oct 2026 00:55:45 GMT
Connection: keep-alive
Content-Type: text/html; charset=UTF-8
Content-Length: 43189
Set-Cookie: community-1=dde5cb07c565e5efd2065c26aaf54c595c7fe3a3cafd760a4a5a4ceeabd10ea9644271d5; httponly; Path=/

第三层:登录验证(用表单提交模拟登录,验证管理员账号可用):

curl -s -c /tmp/rc-cookie.txt -d "username=admin&password=q1w2e3r4" http://127.0.0.1:10020/_admin/login -o /tmp/login.html -w "HTTP %{http_code}\n"
grep -o "admin@rhodecode.local" /tmp/login.html | head -1

实测返回 HTTP 200 且响应页面包含 admin@rhodecode.local,说明登录成功、初始管理员已生效。

第四层(可选):进程模型确认——

supervisorctl -c /root/.rccontrol/supervisor/supervisord.ini status

输出(实测):

community-1:community-1_script   RUNNING   pid 7661, uptime 0:07:40
vcsserver-1:vcsserver-1_script   RUNNING   pid 7625, uptime 0:09:10

四、方案 B:离线安装(--offline)

4.1 缓存与离线机制

rccontrol 每次在线安装都会把 tar 包落入本地缓存 /root/.rccontrol/cache/(实测结构如下),并顺手生成 MANIFEST 快照:

MANIFEST
MANIFEST.old
RhodeCodeCommunity-4.27.1+x86_64-linux_build20221012_1600 -> /opt/rhodecode/store/8mliv4kj7db3qz4jmy3nyca7v7r6kav0-python2.7-rhodecode-enterprise-ce-4.27.1
RhodeCodeCommunity-4.27.1+x86_64-linux_build20221012_1600.tar.bz2
RhodeCodeVCSServer-4.27.1+x86_64-linux_build20221012_1600 -> /opt/rhodecode/store/xwfxr8mj0i9f8fn02pxw4xd9rnwsg23a-python2.7-rhodecode-vcsserver-4.27.1
RhodeCodeVCSServer-4.27.1+x86_64-linux_build20221012_1600.tar.bz2

rccontrol install/upgrade/self-update 均提供 --offline 选项(Use the files in the local Control cache.),安装时不再联网、直接消费缓存内的 tar 包。

4.2 物理隔离环境的离线安装步骤

在能联网的机器上预取三个 tar 包与 MANIFEST(地址见 2.3 节表格),按 md5 校验后拷入目标机缓存目录,再走 --offline 安装:

# 联网机:下载并校验
curl -sS https://dls.rhodecode.com/linux/MANIFEST -o MANIFEST
curl -L -O https://dls.rhodecode.com/linux/RhodeCodeControl-1.24.4+x86_64-linux_build20221012_1600.tar.bz2
curl -L -O https://dls.rhodecode.com/linux/RhodeCodeVCSServer-4.27.1+x86_64-linux_build20221012_1600.tar.bz2
curl -L -O https://dls.rhodecode.com/linux/RhodeCodeCommunity-4.27.1+x86_64-linux_build20221012_1600.tar.bz2
md5sum RhodeCode*.tar.bz2   # 三个值应与 MANIFEST 一致

# 目标机(需先按 3.2 节装好 Control):
mkdir -p /root/.rccontrol/cache
cp RhodeCodeVCSServer-4.27.1+x86_64-linux_build20221012_1600.tar.bz2 /root/.rccontrol/cache/
cp RhodeCodeCommunity-4.27.1+x86_64-linux_build20221012_1600.tar.bz2 /root/.rccontrol/cache/
rccontrol install VCSServer --version 4.27.1 --offline
rccontrol install community --version 4.27.1 --offline

⚠️ 注意:--offline 全流程未在本环境完整实测(在线安装已覆盖同一向导逻辑,差别仅在 tar 包取自缓存);若缓存中缺对应版本 tar 包,--offline 会直接报缺文件,按 2.3 节地址补齐即可。Control 本体(1.24.4)不带缓存机制,物理隔离环境请按 3.2 节的 tar 解压法安装,天然无网络依赖。

五、方案对比与选择建议

维度方案 A:在线安装方案 B:离线安装
网络要求需访问 dls.rhodecode.com(约 470 MB 下载)安装阶段零外联
版本控制MANIFEST 实时拉取,默认最新tar 包预置,版本完全锁定
适用场景可联网服务器、学习与验证物理隔离内网、版本合规锁定
实测程度全流程实测通过缓存结构实测,安装段未完整实测

选择建议:能联网选方案 A(本指南主线,全程可复现);隔离内网或需要版本锁定选方案 B,且两方案的 VCSServer/Community 交互向导完全一致,先在联网机演练一遍再进隔离网是成本最低的路径。

六、systemd 托管与 Nginx 接入

6.1 rccontrol 的进程托管模型

两个实例由 rccontrol 自带的 supervisord(应用商店内 4.1.0 版)托管,配置在 /root/.rccontrol/supervisor/supervisord.ini:每个实例对应一个 [program:<实例名>_script] 段,autostart = true,由 gunicorn 直接拉起应用(--paster 指向各自 ini)。实例级开关记录在 /root/.rccontrol.ini(实测内容):

[instance:community-1]
start_at_boot = True
self_managed_supervisor = False
[instance:vcsserver-1]
start_at_boot = True
self_managed_supervisor = False

start_at_boot = True 表示 supervisord 启动时自动拉起该实例。实测确认:rccontrol 自身不创建 SysV/systemd 开机单元(/etc/init.d/、/etc/systemd/system/ 中均无相关文件,supervisord 由安装过程直接拉起、父进程为 init),因此开机自启需要管理员补一个 systemd 单元,见下节。

6.2 systemd 单元编写与实测

创建 /etc/systemd/system/rccontrol.service:

[Unit]
Description=RhodeCode Control (supervisord)
After=network.target postgresql.service

[Service]
Type=forking
PIDFile=/root/.rccontrol/supervisor/supervisord.pid
ExecStart=/root/.rccontrol-profile/bin/supervisord -c /root/.rccontrol/supervisor/supervisord.ini
ExecStop=/root/.rccontrol-profile/bin/supervisorctl -c /root/.rccontrol/supervisor/supervisord.ini shutdown
ExecReload=/root/.rccontrol-profile/bin/supervisorctl -c /root/.rccontrol/supervisor/supervisord.ini restart all
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

要点:supervisord 默认守护进程化(pidfile 在 /root/.rccontrol/supervisor/supervisord.pid),故 Type=forking + PIDFile;停止走 supervisorctl 的 shutdown 让两个实例优雅退出;数据库单元列在 After= 保证重启后 PostgreSQL 先就绪。

加载并实测完整重启闭环:

systemctl daemon-reload
supervisorctl -c /root/.rccontrol/supervisor/supervisord.ini shutdown

输出(实测):

Shut down

确认进程已退(ps -ef | grep supervisord 无输出),再由 systemd 拉起:

systemctl start rccontrol
sleep 6
systemctl is-active rccontrol

输出(实测):

active
supervisorctl -c /root/.rccontrol/supervisor/supervisord.ini status

输出(实测):

community-1:community-1_script   RUNNING   pid 8812, uptime 0:00:05
vcsserver-1:vcsserver-1_script   RUNNING   pid 8813, uptime 0:00:05

注册开机自启并做最终验证:

systemctl enable rccontrol
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:10020/_admin/login

输出(实测):

Created symlink /etc/systemd/system/multi-user.target.wants/rccontrol.service → /etc/systemd/system/rccontrol.service.
HTTP 200

systemd 拉起后两实例 RUNNING、Web 探活 200,开机自启托管闭环完成。

6.3 Nginx 反向代理(可选)

生产建议 10020 只监听 127.0.0.1、由 Nginx 对外提供 80/443。安装并配置:

apt install -y nginx

写站点配置 /etc/nginx/sites-available/rhodecode:

server {
    listen 8080;
    server_name _;

    client_max_body_size 0;
    proxy_read_timeout 3600;
    proxy_send_timeout 3600;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:10020;
    }
}

参数说明:client_max_body_size 0 取消上传体积限制(大仓库 push 会触发 413);proxy_read_timeout 3600 覆盖大仓库 clone/push 的长连接;X-Forwarded-Proto 供应用识别真实协议(对应 rhodecode.ini 的 force_https 语义,详见《RhodeCode 4.27.1 配置参数详解》)。

启用并启动:

ln -sf /etc/nginx/sites-available/rhodecode /etc/nginx/sites-enabled/rhodecode
rm -f /etc/nginx/sites-enabled/default
systemctl start nginx

验证反代链路:

curl -s -o /dev/null -w "nginx->rhodecode HTTP %{http_code}\n" http://127.0.0.1:8080/_admin/login
curl -sI http://127.0.0.1:8080/ | head -3

输出(实测):

nginx->rhodecode HTTP 200
HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)

七、配置说明

安装即产生四类配置文件,先认位置、改前备份:

文件作用常改项
/root/.rccontrol/community-1/rhodecode.iniCommunity 应用主配置host/port(server:main 段)、sqlalchemy.db1.url(数据库)、app.base_url(对外地址)、邮件与缓存
/root/.rccontrol/vcsserver-1/vcsserver.iniVCSServer 配置host/port、缓存与 workers
/root/.rccontrol/supervisor/supervisord.ini实例进程定义program 段的 command/environment(一般不动)
/root/.rccontrol.inirccontrol 实例开关start_at_boot、self_managed_supervisor

改完 rhodecode.ini 需重启实例生效:

rccontrol restart community-1

逐参数语义、默认值与实测生效验证见《RhodeCode 4.27.1 配置参数详解》;日常启停与升级命令见《RhodeCode 4.27.1 常用 CLI 与运维命令详解》。

八、常见问题(FAQ)

以下 Q1–Q4 均为本环境安装过程中实际发生并解决的排障实录。

Q1:官方引导脚本 get_rccontrol 下载报 502?

现象:执行 curl -o install_rccontrol.sh https://dls.rhodecode.com/get_rccontrol 时服务端返回 502 Bad Gateway(2026-10-28 实测),自解压安装器不可得。

解决:放弃引导脚本,按 3.2 节「MANIFEST → tar 包 → md5 → 解压入 store → 链接 bin」四步等效安装 Control。该路径只依赖 https://dls.rhodecode.com 的静态文件,与引导脚本产物完全一致。

Q2:tar 解压报 bzip2 相关错误?

现象:最小化系统执行 tar xjf 解压 Control 包失败,提示缺少 bzip2(bsdtar/tar 无 bzip2 解压能力时表现为 tar (child): bzip2: Cannot exec 类错误)。

解决:apt install -y bzip2 后重试;这也是 2.1 节把 bzip2 列入基础依赖的原因。

Q3:rccontrol 命令报 "Already running command 'install'"?

现象:上一次 install 中断(如网络断开)后再次执行 rccontrol 命令,报锁占用:

Already running command 'install'

解决:rccontrol 用 /tmp/rccontrol.lock 做单实例互斥,中断后锁未释放;确认没有真正的安装进程在跑后删除该文件即可(实测有效):

rm /tmp/rccontrol.lock

Q4:安装向导初始化数据库报 SCRAM 认证错误?

现象:Community 安装到数据库初始化阶段失败,日志报:

SCRAM authentication requires libpq version 10 or above

定位:Ubuntu 22.04 的 PostgreSQL 14 默认 password_encryption = scram-sha-256,而 RhodeCode 4.27.1 自带的 psycopg2 2.8.4 编译期 libpq 低于 10,不支持 SCRAM。

解决(实测三步):

sudo -u postgres psql
SET password_encryption = 'md5';
ALTER USER rhodecode WITH PASSWORD 'q1w2e3r4';
\q

再把 /etc/postgresql/14/main/pg_hba.conf 中本地连接方法由 scram-sha-256 改为 md5(对应 127.0.0.1/32 与 ::1/128 两行),然后重载:

systemctl reload postgresql

验证密码已改为 md5 格式(输出中 rhodecode 行应以 md5 开头):

sudo -u postgres psql -c "SELECT username, substring(password,1,3) FROM pg_shadow WHERE usename='rhodecode';"

重新执行 rccontrol install community --version 4.27.1 即可通过。

Q5:如何彻底卸载?

见第九章卸载与清理。

九、卸载与清理

按「先实例、后守护、再数据」的顺序逐层移除:

# 1. 停止并卸载实例(⚠️ 本环境为保持运行未实际执行,命令与预期结果如下:
#    rccontrol uninstall 会停止实例进程组并从 supervisor 与实例清单中移除该实例)
rccontrol uninstall community-1
rccontrol uninstall vcsserver-1

# 2. 停止并注销 systemd 单元
systemctl disable --now rccontrol

# 3. 彻底移除 rccontrol 与全部实例(⚠️ 预期:交互确认后删除应用商店、实例目录与 profile)
rccontrol self-destroy

# 4. 手工兜底清理(实测确认这些路径涵盖全部产物)
rm -rf /opt/rhodecode /root/.rccontrol /root/.rccontrol-profile /root/.rccontrol.ini /tmp/rccontrol.lock

# 5. 数据库侧清理(如不再使用)
sudo -u postgres psql -c "DROP DATABASE IF EXISTS rhodecode; DROP USER IF EXISTS rhodecode;"

⚠️ 注意:self-destroy 的交互确认与删除清单以实际版本为准;第 4 步的手工路径覆盖了本指南中出现的全部安装产物,可作为 self-destroy 异常时的兜底。

十、参考链接