Roundup 2.6.0 安装指南（Ubuntu 22.04）

目标：在 Ubuntu 22.04 服务器上从零安装并运行 Roundup 2.6.0 issue 跟踪系统——覆盖 pip 虚拟环境与源码两种安装方案、tracker 实例创建与数据库初始化、systemd 服务托管、Web 界面与 admin 登录验证，以及升级/降级与卸载。已在 Ubuntu 22.04（Python 3.10.12）环境逐条实测通过，全部命令与回显均为真实执行结果。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"）
Python：3.10.12（系统自带 /usr/bin/python3）
Roundup：2.6.0（PyPI 当前最新稳定版，2026-07-13 发布，requires_python >=3.10）
安装方式：venv 虚拟环境 pip 安装（主）/ 官方源码包安装（备）
虚拟环境目录：/opt/roundup-venv
tracker 实例目录：/opt/trackers/support（classic 模板 + sqlite 后端）
运行账户：roundup（系统账户，服务降权运行）
Web 服务：roundup-server 自带服务器，监听 0.0.0.0:8080，托管方式 systemd
示例 admin 账号：admin / q1w2e3r4

二、前置条件

安装 Roundup 前需确认以下条件，逐项给出验证命令与实测回显。

1. 系统为 Ubuntu 22.04 且具备 root 权限

cat /etc/os-release | head -3

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

2. Python 版本 ≥ 3.10（2.6.0 硬性要求）

python3 --version

实测回显：

Python 3.10.12

3. 安装 venv 支持包

Roundup 2.6.0 核心只依赖 Python 标准库，无需数据库服务器等额外软件；唯一需要补的系统包是 python3.10-venv（Ubuntu 默认最小安装不带它）。若已安装，apt 会如实告知：

apt-get update
apt-get install -y python3.10-venv

实测回显（已安装时的输出）：

python3.10-venv is already the newest version (3.10.12-1~22.04.18).
0 upgraded, 0 newly installed, 0 to remove and 12 not upgraded.

4. 确认 PyPI 可达

curl -s -o /dev/null -w "%{http_code}\n" https://pypi.org/simple/roundup/

实测回显：

⚠️ 排障实录：本环境系统环境变量预置了 http_proxy/https_proxy 指向一个已失效的代理地址，pip install 直接报 ProxyError('Cannot connect to proxy.', ... Connection refused) 并以 ERROR: Could not find a version that satisfies the requirement roundup (from versions: none) 收场。定位方法：报错出现 Cannot connect to proxy 说明 pip 在尝试走代理而非直连。解决：清空代理变量后重试（env -u http_proxy -u https_proxy pip install roundup，或临时 unset http_proxy https_proxy）。同理，若服务器上配置了代理，curl 访问本机地址也会被代理拦截，需加 --noproxy "*" 参数。

三、版本选型说明

Roundup 采用「每年 7 月一个稳定版」的发布节奏，各版本对 Python 的要求不同（数据实查自 PyPI，查询日期 2026-10-24）：

版本	PyPI 上传日期	requires_python	适用判断
2.6.0	2026-07-13	`>=3.10`	新部署首选，本文基线
2.5.0	2025-07-13	`>=3.7`	存量 Python 3.7–3.9 环境可用的最新版
2.4.0	2024-07-13	`>=2.7`（含 Python 2）	仅存量 Python 2 tracker 维护用，新部署禁用

解读：本指南目标环境 Python 3.10.12，直接安装 2.6.0。查询 PyPI 全部可发行版本的命令（实测回显见第八章）：

pip index versions roundup

四、在线安装方案（A：pip 虚拟环境，官方推荐）

4.1 方案说明

官方安装文档推荐的Production 路径即「venv + pip install roundup」：程序库安装进独立虚拟环境，与系统 Python 包隔离；tracker 实例（配置 + 数据）独立存放在 /opt/trackers/ 下。整个过程无需编译器与数据库服务，两三分钟完成。

4.2 创建运行账户与目录

Roundup 的 Web 服务拒绝以 root 运行（实测报错见第九章 FAQ），先创建专用系统账户：

useradd -r -m -s /usr/sbin/nologin roundup
mkdir -p /opt/trackers

useradd 成功时无输出。验证账户：

id roundup

实测回显：

uid=999(roundup) gid=999(roundup) groups=999(roundup)

4.3 创建虚拟环境

python3 -m venv /opt/roundup-venv

成功时无输出。验证虚拟环境的 pip 可用：

/opt/roundup-venv/bin/pip --version

实测回显：

pip 22.0.2 from /opt/roundup-venv/lib/python3.10/site-packages/pip (python 3.10)

4.4 pip 安装 Roundup

/opt/roundup-venv/bin/pip install roundup

实测回显（完整过程，roundup 在 PyPI 以 sdist 分发，pip 会现场构建 wheel）：

Collecting roundup
  Downloading roundup-2.6.0.tar.gz (4.8 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.8/4.8 MB 80.4 kB/s eta 0:00:00
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'done'
  Preparing metadata (pyproject.toml): started
  Preparing metadata (pyproject.toml): finished with status 'done'
Building wheels for collected packages: roundup
  Building wheel for roundup (pyproject.toml): started
  Building wheel for roundup (pyproject.toml): finished with status 'done'
  Created wheel for roundup: filename=roundup-2.6.0-py3-none-any.whl size=2829300 sha256=d342e5a35d6f587af4556cef4b9cf810ce25c46899fbe984621b8ddcd29cf317
  Stored in directory: /root/.cache/pip/wheels/87/dc/39/d0b736b08571afdc349cc698fda14fe8d764d38c150fdb8366
Successfully built roundup
Installing collected packages: roundup
Successfully installed roundup-2.6.0

4.5 安装验证

安装完成后得到 6 个命令行工具。先看元数据：

/opt/roundup-venv/bin/pip show roundup | head -8

实测回显：

Name: roundup
Version: 2.6.0
Summary: A simple-to-use and -install issue-tracking system with command-line, web and e-mail interfaces. Highly customisable.
Home-page: https://www.roundup-tracker.org
Author: Richard Jones
Author-email: richard@users.sourceforge.net
License:
Location: /opt/roundup-venv/lib/python3.10/site-packages

再列命令行工具并确认版本：

ls /opt/roundup-venv/bin/ | grep roundup
/opt/roundup-venv/bin/roundup-admin -v

实测回显：

roundup-admin
roundup-demo
roundup-gettext
roundup-mailgw
roundup-server
roundup-xmlrpc-server
2.6.0 (python 3.10.12)

💡 说明：roundup-admin 没有 --version 长选项（实测会报 Problem: option --version not recognized），版本查询用小写 -v。六个工具的分工：roundup-admin（实例管理）、roundup-server（Web 服务）、roundup-mailgw（邮件网关）、roundup-xmlrpc-server（XML-RPC 服务）、roundup-gettext（翻译字符串提取）、roundup-demo（一键 demo 实例）。

五、源码安装方案（B：离线包/断网环境）

5.1 方案说明

内网服务器无法访问 PyPI 时，可在有网的机器上用 pip download 拿到官方源码包（roundup 的发行包即源码包），拷贝到目标服务器解压安装。该方案安装结果与方案 A 完全一致（同为 2.6.0）。

5.2 下载源码包

在可联网的机器上执行：

mkdir -p /opt/src
env -u http_proxy -u https_proxy /opt/roundup-venv/bin/pip download roundup==2.6.0 --no-deps -d /opt/src

实测回显：

Saved /opt/src/roundup-2.6.0.tar.gz
Successfully downloaded roundup

确认文件（4.8 MB 左右）：

ls -la /opt/src/

实测回显：

total 4724
drwxr-xr-x 2 root root    4096 Oct 24 05:38 .
drwxr-xr-x 1 root root    4096 Oct 24 05:38 ..
-rw-r--r-- 1 root root 4829062 Oct 24 05:38 roundup-2.6.0.tar.gz

5.3 解压

把 roundup-2.6.0.tar.gz 拷贝到目标服务器后解压：

cd /opt/src && tar -xzf roundup-2.6.0.tar.gz
ls roundup-2.6.0/ | grep -E "setup|pyproject"

实测回显：

pyproject.toml
setup.cfg
setup.py

⚠️ 排障实录：不要用 tar -xzvf ... | head -8 这类「解压同时只看前几行」的管道写法——head 退出后 tar 收到 SIGPIPE 会被提前杀死，目录解压不完整（本环境实测解压只剩 8 个文件），随后 pip install 报 ERROR: Directory '...' is not installable. Neither 'setup.py' nor 'pyproject.toml' found.。解压后先确认 setup.py 与 pyproject.toml 存在再安装。

5.4 从源码安装

/opt/roundup-venv/bin/pip install /opt/src/roundup-2.6.0

实测回显（本环境此前已装 2.6.0，pip 自动先卸后装）：

Installing collected packages: roundup
  Attempting uninstall: roundup
    Found existing installation: roundup 2.6.0
    Uninstalling roundup-2.6.0:
      Successfully uninstalled roundup-2.6.0
Successfully installed roundup-2.6.0

⚠️ 排障实录：pip install /opt/src/roundup-2.6.0 这类本地目录安装默认启用构建隔离，会尝试联网拉取构建依赖；若环境变量中残留失效代理，子进程构建阶段会报 exit code: 1 并提示 This error originates from a subprocess。解决：清空代理变量（env -u http_proxy -u https_proxy pip install ...）或加 --no-build-isolation。

5.5 安装验证

/opt/roundup-venv/bin/roundup-admin -v

实测回显：

2.6.0 (python 3.10.12)

六、方案对比与选择建议

维度	方案 A：pip 虚拟环境	方案 B：源码包安装
是否需联网	安装机需访问 PyPI	仅下载机需联网，目标机离线可装
版本固定	跟随 PyPI（可 `==` 锁定）	源码包即固定版本
升级方式	`pip install -U roundup` 一条命令	重新 download + install
适用场景	能联网的服务器（官方推荐路径）	内网隔离、审计要求留档源码包

选择建议：可联网选方案 A；隔离内网选方案 B 并把 roundup-2.6.0.tar.gz 归档到内部制品库。

七、Tracker 实例创建与初始化（两种方案通用）

安装好的只是 Roundup 程序库；真正承载业务的是「tracker 实例」——一个含 config.ini、schema.py、html/ 模板与数据库的目录。本章从零创建 support 实例。

7.1 安装 tracker 实例

roundup-admin install 是交互式命令，依次询问 tracker 目录、模板与后端。五套可选模板为 classic、devel、responsive、jinja2、minimal；数据库后端可选 anydbm、sqlite（本示例选 sqlite）：

printf "/opt/trackers/support\nclassic\nsqlite\n" | /opt/roundup-venv/bin/roundup-admin install

实测回显：

Enter tracker home: Templates:: classic, devel, responsive, jinja2, minimal
Select template [classic]: Back ends:: anydbm, sqlite
Select backend [anydbm]:
---------------------------------------------------------------------------
 You should now edit the tracker configuration file:
   /opt/trackers/support/config.ini
 ... at a minimum, you must set following options:
   [tracker]: web
   [mail]: domain, host

 If you wish to modify the database schema,
 you should also edit the schema file:
   /opt/trackers/support/schema.py
 You may also change the database initialisation file:
   /opt/trackers/support/initial_data.py
 ... see the documentation on customizing for more information.

 You MUST run the "roundup-admin initialise" command once you've performed
 the above steps.
---------------------------------------------------------------------------

确认实例目录结构：

ls /opt/trackers/support/

实测回显：

TEMPLATE-INFO.txt
__pycache__
config.ini
detectors
extensions
html
initial_data.py
schema.py

7.2 修改最小必填配置

安装器提示必须设置 [tracker] 节的 web 与 [mail] 节的 domain。web 是对外访问地址（必须以 / 结尾），domain 用于拼接系统发件地址（本示例 admin 邮箱将拼成 roundup-admin@example.net）：

sed -i "s|^#web = NO DEFAULT|web = http://localhost:8080/support/|" /opt/trackers/support/config.ini
sed -i "s|^#domain = NO DEFAULT|domain = example.net|" /opt/trackers/support/config.ini
grep -nE "^(web|domain) = " /opt/trackers/support/config.ini

实测回显：

202:web = http://localhost:8080/support/
884:domain = example.net

7.3 初始化数据库并设置 admin 密码

initialise 创建数据库文件并内置两个用户：admin（超级管理员）与 anonymous（匿名）。密码作为参数直接传入（示例口令 q1w2e3r4，生产环境请改强口令）：

/opt/roundup-venv/bin/roundup-admin -i /opt/trackers/support initialise q1w2e3r4

成功时无输出（exit 0）。确认数据库文件已生成：

ls -la /opt/trackers/support/db/

实测回显：

total 352
drwxr-xr-x 2 root root   4096 Oct 24 05:34 .
drwxr-xr-x 7 root root   4096 Oct 24 05:34 ..
-rw-r--r-- 1 root root 348160 Oct 24 05:34 db

把实例目录交给运行账户：

chown -R roundup:roundup /opt/trackers/support /opt/roundup-venv

7.4 systemd 托管 roundup-server

写入服务单元文件 /etc/systemd/system/roundup-server.service：

cat > /etc/systemd/system/roundup-server.service <<EOF
[Unit]
Description=Roundup issue tracker web server
After=network.target

[Service]
Type=simple
User=roundup
Group=roundup
ExecStart=/opt/roundup-venv/bin/roundup-server -n 0.0.0.0 -p 8080 support=/opt/trackers/support
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

单元文件逐项说明：User=roundup/Group=roundup 让服务以专用账户运行（roundup-server 自身也拒绝 root，见第九章 FAQ）；-n 0.0.0.0 监听所有网卡（默认仅 localhost）；-p 8080 端口（roundup-server 默认端口即 8080）；support=/opt/trackers/support 把实例挂载在 Web 路径 /support/ 下（一个 roundup-server 进程可同时挂多个 tracker，写成多个 名字=目录 参数即可）；Restart=on-failure 异常退出自动拉起。

启动并设开机自启：

systemctl daemon-reload
systemctl enable --now roundup-server

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/roundup-server.service → /etc/systemd/system/roundup-server.service.

确认运行状态：

systemctl is-active roundup-server
systemctl status roundup-server --no-pager -l | head -12

实测回显：

active
● roundup-server.service - Roundup issue tracker web server
     Loaded: loaded (/etc/systemd/system/roundup-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-10-24 05:36:14 UTC; 2s ago
   Main PID: 4117 (roundup-server)
      Tasks: 1 (limit: 629145)
     Memory: 20.8M
        CPU: 121ms
     CGroup: /system.slice/roundup-server.service
             └─4117 /opt/roundup-venv/bin/python3 /opt/roundup-venv/bin/roundup-server -n 0.0.0.0 -p 8080 support=/opt/trackers/support

Oct 24 05:36:14 roundup-server systemd[1]: Started Roundup issue tracker web server.

常驻内存约 20 MB，资源占用非常轻。

7.5 验证 Web 界面与 admin 登录

curl --noproxy "*" -s -o /dev/null -w "web_code=%{http_code}\n" http://localhost:8080/support/

实测回显：

web_code=200

再验证 admin 凭据（-u 用户:密码）能否管理数据库——列出 classic 模板内置的 8 个 issue 状态：

/opt/roundup-venv/bin/roundup-admin -i /opt/trackers/support -u admin:q1w2e3r4 list status

实测回显：

   1: unread
   2: deferred
   3: chatting
   4: need-eg
   5: in-progress
   6: testing
   7: done-cbb
   8: resolved

查看内置用户（domain = example.net 已生效于 admin 邮箱）：

/opt/roundup-venv/bin/roundup-admin -i /opt/trackers/support -u admin:q1w2e3r4 table user id,username,realname,address

实测回显：

Id Username  Realname Address
1  admin     None     roundup-admin@example.net
2  anonymous None     None

至此安装完成：浏览器访问 http://<服务器IP>:8080/support/ 即可使用 tracker，admin 登录口令为初始化时设置的 q1w2e3r4。日常命令使用见本专栏《Roundup 2.6.0 常用 CLI 命令与工具详解》一篇，配置项体系见《Roundup 2.6.0 配置参数详解》一篇。

八、升级、降级与多版本管理

8.1 查询可用版本

env -u http_proxy -u https_proxy /opt/roundup-venv/bin/pip index versions roundup

实测回显：

WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
roundup (2.6.0)
Available versions: 2.6.0, 2.5.0, 2.4.0, 2.3.0, 2.2.0, 2.1.0, 2.0.0, 1.6.1, 1.6.0, 1.5.1, 1.5.0, 1.4.21, 1.4.20, 1.4.19, 1.4.18, 1.4.17, 1.4.16, 1.4.15, 1.4.14, 1.4.13, 1.4.12, 1.4.11, 1.4.10, 1.4.9, 1.4.8, 1.4.7, 1.4.6, 1.4.5.1, 1.4.4, 1.4.3, 1.4.2, 1.4.1, 1.4.0, 1.3.3, 1.3.2, 1.3.1, 1.3.0, 1.2.1, 1.2.0, 1.1.2, 1.1.1, 1.1.0, 1.0.1, 1.0, 0.8.6, 0.8.5, 0.8.4, 0.8.3, 0.8.2, 0.7.12, 0.6.11
  INSTALLED: 2.6.0
  LATEST:    2.6.0

8.2 升级

/opt/roundup-venv/bin/pip install -U roundup

升级后需重启服务并执行数据迁移（schema 变更时自动处理）：

systemctl restart roundup-server
/opt/roundup-venv/bin/roundup-admin -i /opt/trackers/support migrate

migrate 在无待迁移项时静默通过。升级前务必先备份数据目录：cp -a /opt/trackers/support /backup/support-$(date +%F)。

8.3 降级

降级就是指定版本号安装，pip 会自动卸载现有版本：

/opt/roundup-venv/bin/pip install "roundup==2.5.0"

实测回显：

    Found existing installation: roundup 2.6.0
    Uninstalling roundup-2.6.0:
      Successfully uninstalled roundup-2.6.0
Successfully installed roundup-2.5.0

⚠️ 注意：跨版本降级（如 2.6.0 → 2.5.0）前必须确认数据库 schema 兼容；Roundup 对库结构有版本标记，若 migrate 已写入新结构，直接降级可能导致旧版本程序拒绝打开数据库。降级前用 8.2 的备份命令恢复数据目录，再安装旧版程序。

降级演练完成后升回最新版并验证服务：

/opt/roundup-venv/bin/pip install -U roundup
systemctl restart roundup-server

实测回显（尾部）：

Successfully uninstalled roundup-2.5.0
Successfully installed roundup-2.6.0

systemctl is-active roundup-server
curl --noproxy "*" -s -o /dev/null -w "web_code=%{http_code}\n" http://localhost:8080/support/

实测回显：

active
web_code=200

8.4 多版本并存

同一台服务器跑多个 tracker、分别固定在不同版本时，为每个版本建独立 venv 即可（venv 天然隔离）：

python3 -m venv /opt/roundup-venv-2.5
/opt/roundup-venv-2.5/bin/pip install "roundup==2.5.0"

再为对应服务写独立 systemd 单元（如 roundup-server-2.5.service，ExecStart 指向该 venv 的 roundup-server 并使用不同端口与实例目录）。

九、常见问题（FAQ）

Q1：roundup-server 启动报 Can't run as root! 怎么办？

这是 2.6.0 的强制安全策略——Web 服务禁止 root 运行。实测回显：

Can't run as root!

解决：以专用账户运行。命令行临时测试加 -u roundup -g roundup 参数（或用 su -s /bin/bash roundup -c '/opt/roundup-venv/bin/roundup-server -n 0.0.0.0 -p 8080 support=/opt/trackers/support' 切换后启动）；systemd 托管则如 7.4 所示写 User=roundup/Group=roundup，ExecStart 里无需再加 -u/-g。

Q2：pip 安装报 Could not find a version that satisfies the requirement roundup (from versions: none)？

先看报错上文是否有 ProxyError('Cannot connect to proxy.', ...)——若服务器环境变量里配置了失效代理，pip 会全部走代理并失败。解决：env -u http_proxy -u https_proxy pip install roundup 或修正代理配置。若确需代理访问外网，把代理地址改成真实可用的即可。

Q3：pip install <解压目录> 报 Neither 'setup.py' nor 'pyproject.toml' found？

九成是解压不完整（参考 5.3 排障实录：tar | head 管道写法会让 tar 被 SIGPIPE 杀死）。完整解压后确认 ls <目录> 能看到 setup.py 与 pyproject.toml 再装。

Q4：curl 访问 http://localhost:8080/support/ 返回 000 但端口明明在监听？

本环境实测踩过：服务器配置了 http_proxy 环境变量后，curl 对 localhost 的请求也会发给代理，代理连不通就返回 000。加 --noproxy "*" 参数绕过代理即可。程序化探测端口可用 python3 -c "import socket; s=socket.socket(); s.settimeout(2); print(s.connect_ex(('127.0.0.1',8080)))"（回显 0 表示端口可连）。

Q5：roundup-admin --version 为什么报错？

该命令没有 --version 长选项，实测报 Problem: option --version not recognized。用 roundup-admin -v，回显格式为 2.6.0 (python 3.10.12)。

Q6：initialise 之后 admin 密码忘了？

用 roundup-admin -i <实例目录> -u admin:<旧密码> set user1 password=<新密码> 重设；若旧密码彻底遗失，最直接的办法是停止服务、备份后删除 db/ 目录重新 initialise（数据会清空，务必先备份）。日常密码与用户管理操作见《Roundup 2.6.0 常用 CLI 命令与工具详解》一篇。

十、卸载与清理

按依赖反向顺序清理：

# 1. 停止并禁用服务
systemctl disable --now roundup-server
# 2. 删除服务单元
rm /etc/systemd/system/roundup-server.service
systemctl daemon-reload
# 3. 删除实例数据（含全部 issue 数据，操作前确认无需保留）
rm -rf /opt/trackers/support
# 4. 删除虚拟环境（程序本体）
rm -rf /opt/roundup-venv
# 5. 删除运行账户及家目录
userdel -r roundup

以上每条命令成功时均无输出。验证清理干净：

id roundup
ls /opt/roundup-venv

实测回显（均应为不存在）：

id: 'roundup': no such user
ls: cannot access '/opt/roundup-venv': No such file or directory

十一、参考链接

官方安装文档（含更多 Web 部署形态：WSGI/FastCGI/CGI）：https://www.roundup-tracker.org/docs/installation.html
PyPI 项目页：https://pypi.org/project/roundup/
官方文档中心：https://roundup-tracker.org/docs.html
升级指南：https://www.roundup-tracker.org/docs/upgrading.html
roundtup-server 与配置参考：https://www.roundup-tracker.org/docs/customizing.html
本专栏姊妹篇：《Roundup 2.6.0 介绍与选型指南》