Trac 1.6 安装指南（pip/tracd 形态）

目标：在一台 Ubuntu 22.04 服务器上以 pip 安装 Trac 1.6，用 trac-admin initenv 初始化 SQLite 项目环境，以 tracd 独立服务对外提供 Web 访问，并完成 Digest 认证、systemd 托管、数据目录规划与备份/升级要点。Trac 无官方系统包与镜像分发，pip + tracd 是官方主推的裸机部署形态。全部命令已在 Ubuntu 22.04 LTS + Python 3.10.12 环境逐条实测（组件定位与选型见《Trac 1.6 介绍与选型指南》）。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）服务器形态；
Python：3.10.12（系统自带，/usr/bin/python3）；
Trac：1.6（PyPI 最新稳定版，2023-09-23 发布，查询日期 2026-10-31）；
服务端口：8140（示例，可自行更换）；
项目环境目录：/var/trac/myproject（主项目）、/var/trac/demo（本文验证用辅助环境）；
认证：htdigest 文件 /var/trac/users.htdigest，Realm TracRealm；
演示账号：admin / q1w2e3r4；
数据库：SQLite（sqlite:db/trac.db，环境目录内单文件）。

二、前置条件

2.1 系统依赖

apt update
apt install -y python3 python3-pip      # Python 3 与 pip（Ubuntu 22.04 默认已带 python3）

可选依赖（按需）：

apache2-utils：提供 htdigest 命令行工具（生成认证文件用，也可用 Python 代替，见 10.2）；
数据库驱动：python3-psycopg2（PostgreSQL）或 pymysql（MySQL），默认 SQLite 无需任何驱动；
SVN 集成：python3-subversion（Subversion Python 绑定）；Git 集成仅要求系统装有 git 命令。

2.2 目录与权限规划

mkdir -p /var/trac                      # 存放所有项目环境的父目录

⚠️ 注意：生产环境建议创建专用系统用户（如 trac）作为环境目录属主与服务运行身份，本文为简化演示以 root 运行实测；systemd 单元中给出的 www-data 即降权示例。

三、版本选型说明

为什么是 1.6：截至 2026-10-31，PyPI 上 Trac 最新稳定版即 1.6（2023-09-23 发布），pip install Trac 默认安装该版本（实测回显见 4.2）；1.6 系列要求 Python ≥ 3.5，是官方 Python 3 化后的稳定线（来源：pypi.org/project/Trac，查询日期 2026-10-31）；
依赖链极短：实测安装仅自动带入 jinja2（模板）与 MarkupSafe 两个纯 Python 依赖，无需编译环节；
数据库：SQLite 由 Python 内置 sqlite3 模块支持，零额外安装；PostgreSQL/MySQL 仅在需要时装驱动；
部署形态：本文覆盖 pip 安装 + tracd 独立服务（小中型团队最简形态）；如需并入 Apache/Nginx，可通过 WSGI 接口承载（trac-admin deploy 会生成 trac.wsgi，见 8.3）。

四、在线安装方案（pip + PyPI）

4.1 方案说明

服务器可访问公网或内网 PyPI 镜像时，直接 pip install Trac，这是官方文档 TracInstall 的首选方式。实际安装时若默认源较慢，可加 -i 指定国内镜像。

4.2 安装步骤

pip3 install Trac
# 网络受限时改用国内镜像：
# pip3 install Trac -i https://pypi.tuna.tsinghua.edu.cn/simple

实测回显（Ubuntu 22.04，root 身份）：

Collecting Trac
  Using cached Trac-1.6-py3-none-any.whl (2.9 MB)
Requirement already satisfied: setuptools>=30.3 in /usr/lib/python3/dist-packages (from Trac) (59.6.0)
Collecting jinja2>=2.9.3
  Using cached jinja2-3.1.6-py3-none-any.whl (134 kB)
Collecting MarkupSafe>=2.0
  Using cached markupsafe-3.0.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (20 kB)
Installing collected packages: MarkupSafe, jinja2, Trac
Successfully installed MarkupSafe-3.0.4 Trac-1.6 jinja2-3.1.6
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

💡 说明：结尾的 root 警告不影响使用；生产环境如需隔离可用 pip3 install --user Trac 或 venv，服务单元中的 ExecStart 路径随之调整。

4.3 安装验证

tracd --version

实测回显：

tracd 1.6

pip3 show Trac

实测回显（节选）：

Name: Trac
Version: 1.6
Summary: Integrated SCM, wiki, issue tracker and project environment

五、离线安装方案（wheel 离线包）

5.1 方案说明

内网隔离服务器无法直连 PyPI 时，在一台能联网的机器上用 pip download 把 Trac 及全部依赖下载为 wheel 包，拷贝到内网后用 pip install --no-index --find-links 离线安装。

5.2 联网机下载 wheel 包

pip3 download Trac -d /tmp/trac-wheels -i https://pypi.tuna.tsinghua.edu.cn/simple

实测回显（下载完成后目录内容）：

-rw-r--r-- 1 root root 2876098 Oct 31 04:26 Trac-1.6-py3-none-any.whl
-rw-r--r-- 1 root root  134899 Oct 31 04:26 jinja2-3.1.6-py3-none-any.whl
-rw-r--r-- 1 root root   20712 Oct 31 04:26 markupsafe-3.0.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
-rw-r--r-- 1 root root  876263 Oct 31 04:26 setuptools-84.2.1-py3-none-any.whl

共 4 个包约 3.8 MB，拷贝整个目录到内网机即可。

5.3 内网机离线安装

pip3 install --no-index --find-links=/tmp/trac-wheels Trac

实测回显（--no-index 强制不访问任何源，全部从本地 wheel 解析）：

WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

安装后目录中出现 Trac-1.6.dist-info、jinja2、bin/tracd 等完整程序文件，离线安装成功。

5.4 方案验证

tracd --version    # 输出 tracd 1.6 即成功

六、安装方案对比与选择建议

维度	在线 pip 安装	离线 wheel 安装
是否需联网	需（或内网镜像源）	不需（一次性拷贝）
版本控制	装到即 PyPI 最新（1.6）	wheel 固化版本，升级需重新 download
依赖解析	pip 自动解决	download 时已固化
适用场景	可联网服务器、快速部署	内网隔离、批量装机、版本锁定
服务名/进程	相同：tracd（或 systemd 托管）	相同

选择建议：可联网选在线；内网隔离或需版本审计选离线 wheel。

七、初始化项目环境（trac-admin initenv）

7.1 非交互初始化（推荐用于自动化）

trac-admin /var/trac/myproject initenv "My Project" sqlite:db/trac.db

实测回显（完整）：

Creating a new Trac environment at /var/trac/myproject

Project environment for 'My Project' created.

You may configure the environment by editing the file:

  /var/trac/myproject/conf/trac.ini

You can run the Trac standalone web server `tracd` and point
your browser to http://localhost:8000/myproject.

  tracd --port 8000 /var/trac/myproject

Navigate to "Help/Guide" to browse the documentation for Trac,
including information on further setup (such as deploying Trac
to a real web server).

The latest documentation can also be found on the project
website:

  https://trac.edgewall.org/

7.2 交互式初始化

省略参数进入交互问答，实测共两问（项目名、数据库连接串，均有默认值可直接回车）：

trac-admin /var/trac/interactive initenv     # 管道喂入两行回答：项目名、连接串

实测回显（节选）：

Trac will first ask a few questions about your environment
in order to initialize and prepare the project database.

 Please enter the name of your project.
 This name will be used in page titles and descriptions.

Project Name [My Project]>
 Please specify the connection string for the database. By default,
 a local SQLite database is created in the environment directory.
 It is also possible to use an existing MySQL or PostgreSQL database
 (check the Trac documentation for the connection string syntax).

Database connection string [sqlite:db/trac.db]>

Project environment for 'Interactive Demo' created.

7.3 环境目录结构

初始化完成后的完整目录（find /var/trac/myproject -type f -o -type d 实测）：

/var/trac/myproject
/var/trac/myproject/README
/var/trac/myproject/VERSION
/var/trac/myproject/conf
/var/trac/myproject/conf/trac.ini
/var/trac/myproject/conf/trac.ini.sample
/var/trac/myproject/db
/var/trac/myproject/db/trac.db
/var/trac/myproject/htdocs
/var/trac/myproject/log
/var/trac/myproject/log/trac.log
/var/trac/myproject/plugins
/var/trac/myproject/templates
/var/trac/myproject/templates/site_footer.html.sample
/var/trac/myproject/templates/site_head.html.sample
/var/trac/myproject/templates/site_header.html.sample

初始化 + 默认 61 个内置 Wiki 页后 SQLite 库实测约 724 KB。conf/trac.ini 的逐项参数见《Trac 1.6 配置参数详解》。

八、tracd 独立服务启动与访问验证

8.1 前台启动（快速验证）

tracd --port 8000 /var/trac/myproject

浏览器访问 http://<服务器IP>:8000/myproject。调试排障建议先用前台模式看实时输出。

8.2 daemon 后台模式（实测）

tracd -d --pidfile /tmp/tracd.pid --port 8141 /var/trac/demo

实测验证链：

cat /tmp/tracd.pid   → 4290
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8141/demo
                     → 200
kill $(cat /tmp/tracd.pid)   → 进程退出，服务停止

8.3 导出静态资源与 WSGI 派发脚本（deploy）

trac-admin /var/trac/myproject deploy /tmp/trac-deploy

实测回显：

Copying resources from:
  trac.web.chrome.Chrome
    /usr/local/lib/python3.10/dist-packages/trac/htdocs
    /var/trac/myproject/htdocs
Creating scripts.
/tmp/trac-deploy
/tmp/trac-deploy/htdocs
/tmp/trac-deploy/htdocs/common
/tmp/trac-deploy/htdocs/site
/tmp/trac-deploy/cgi-bin
/tmp/trac-deploy/cgi-bin/trac.fcgi
/tmp/trac-deploy/cgi-bin/trac.wsgi
/tmp/trac-deploy/cgi-bin/trac.cgi

htdocs/common 是 Trac 全部静态资源（CSS/JS/图标），交给前端 Web 服务器直接服务可显著提速；cgi-bin/ 下自动生成 trac.wsgi（mod_wsgi/uWSGI/gunicorn 入口）、trac.fcgi、trac.cgi 三种派发脚本。

8.4 Digest 认证与登录实测

生成认证文件（htdigest 来自 apache2-utils，-c 表示新建文件）：

htdigest -c /var/trac/users.htdigest TracRealm admin

实测回显（两次输入密码 q1w2e3r4）：

Adding password for admin in realm TracRealm.
New password: Re-type new password:

生成的文件内容为 admin:TracRealm:<MD5 哈希>（admin:TracRealm:dbec3284dbcf38fa2c2caf8df376bf31）。

带认证启动 tracd：

tracd --port 8140 --hostname 0.0.0.0 \
  --auth=*,/var/trac/users.htdigest,TracRealm \
  /var/trac/myproject

登录链路实测（curl + digest）：

# 1) 直接访问项目路径：无认证质询，返回 403（匿名身份）
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8140/myproject
403

# 2) 访问 /myproject/login：先 401 质询，digest 重试后 302 登录成功
curl -v --digest -u admin:q1w2e3r4 -c /tmp/cj.txt http://127.0.0.1:8140/myproject/login
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: Digest realm="TracRealm", nonce="f45d2733f56b30e8224bf5c1f1bbcf40", qop="auth", stale="false"
> Authorization: Digest username="admin", realm="TracRealm", ...
< HTTP/1.1 302 Found

# 3) 携带会话 Cookie 再访问项目首页：200，正常渲染
curl -s -b /tmp/cj.txt -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8140/myproject
200

8.5 排障实录：403 而不是 401

现象：curl http://server:8140/myproject 直接返回 403 Forbidden，且响应头没有 WWW-Authenticate，认证根本没被触发；trac.log 中记录：

Trac[main] WARNING: [127.0.0.1] HTTPForbidden: 403 Forbidden (WIKI_VIEW privileges are required to perform this operation on WikiStart. You don't have the required permissions.), <RequestWithSession "GET '/'">

根因：tracd 的认证中间件只挂在 <环境名>/login 这一个路径上（源码 trac/web/standalone.py 的 AuthenticationMiddleware 仅当 path_parts[self.part] == 'login' 时执行认证）。直接访问项目路径的请求永远以匿名身份进入；若匿名权限已被收紧（见《Trac 1.6 常用 CLI 命令详解》权限实操），就会得到 403 而非 401。

解决：浏览器中首次登录必须访问 http://server:8140/myproject/login，输入凭据后 Trac 建立会话 Cookie，再访问其他页面即为登录态。密码哈希可用 Python 校验：hashlib.md5(b"admin:TracRealm:q1w2e3r4").hexdigest() 应与 htdigest 文件中的值一致。

九、systemd 服务托管

9.1 单元文件

写入 /etc/systemd/system/tracd.service：

[Unit]
Description=Trac standalone web server (tracd)
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
ExecStart=/usr/local/bin/tracd --port 8140 --hostname 0.0.0.0 --auth=*,/var/trac/users.htdigest,TracRealm /var/trac/myproject
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

⚠️ 注意：User=www-data 时需保证该用户对 /var/trac/myproject 有读写权限（chown -R www-data:www-data /var/trac/myproject），否则启动后报数据库只读错误。

9.2 单元文件语法校验

用 systemd-analyze verify 预检单元文件（在一台有 systemd 的机器上执行）：

$ systemd-analyze verify /etc/systemd/system/tracd.service
tracd.service: Command /usr/local/bin/tracd is not executable: No such file or directory

仅提示 tracd 二进制路径在校验机上不存在（该路径属于部署目标服务器），单元文件语法本身无任何告警，即通过校验。

9.3 启用与开机自启

chown -R www-data:www-data /var/trac/myproject   # 运行身份需可写环境目录
systemctl daemon-reload
systemctl enable --now tracd.service             # 启动并设为开机自启
systemctl status tracd.service --no-pager        # 确认 active (running)

9.4 无 systemd 环境的替代方案

如运行环境无 systemd（或最小化容器运行时），使用 tracd 自带的 daemon 模式 + pidfile 托管（实测见 8.2）：tracd -d --pidfile /var/run/tracd.pid ...，停止用 kill $(cat /var/run/tracd.pid)。

十、配置说明

全部配置集中在环境目录 conf/trac.ini（初始化时同时生成 trac.ini.sample 对照样本），逐项参数详解见《Trac 1.6 配置参数详解》；
监听端口/绑定地址/认证文件都是 tracd 启动参数而非 trac.ini 配置，持久化要改 systemd 单元或启动脚本（参数全解见《Trac 1.6 常用 CLI 命令详解》）；
多项目：tracd 可同时挂多个环境目录，或用 -e /var/trac 以父目录模式自动发现全部环境。

10.1 多环境启动示例

tracd -p 8140 -e /var/trac                          # 父目录模式：/var/trac 下每个子目录一个项目
tracd -p 8140 /var/trac/myproject /var/trac/demo    # 显式列出多个环境

10.2 无 apache2-utils 时生成 htdigest

python3 -c "import hashlib; print('admin:TracRealm:' + hashlib.md5(b'admin:TracRealm:q1w2e3r4').hexdigest())"
# 输出：admin:TracRealm:dbec3284dbcf38fa2c2caf8df376bf31（与 htdigest 工具生成结果一致，实测）

十一、数据目录与备份

11.1 热备份（hotcopy，不停止服务）

trac-admin /var/trac/myproject hotcopy /tmp/backup-20261031

实测回显：

Hotcopying /var/trac/myproject to /tmp/backup-20261031 ...
Hotcopy done.

备份目录内容与环境目录一致（README、VERSION、conf、db、htdocs、log、plugins、templates）。

11.2 冷备份

停服后直接打包整个环境目录即可（SQLite 单文件，物理拷贝安全）：

systemctl stop tracd.service
tar czf /backup/trac-myproject-$(date +%F).tgz -C /var/trac myproject
systemctl start tracd.service

💡 说明：SQLite 形态下环境目录自包含（库文件 db/trac.db + 配置 + 附件），整目录打包即可完整迁移；换用 PostgreSQL/MySQL 后备份策略随数据库走。

十二、升级要点

先备份：trac-admin /var/trac/myproject hotcopy /backup/pre-upgrade；
升级包：pip3 install --upgrade Trac；
升级环境结构：trac-admin /var/trac/myproject upgrade（迁移数据库 schema、环境目录元数据）。实测当前已是 1.6 的回显：

Database is up to date, no upgrade necessary.

升级内置 Wiki 页：trac-admin /var/trac/myproject wiki upgrade（把新版官方文档页合并到本地 Wiki）；
重启服务：systemctl restart tracd.service；
回滚：升级失败时直接用 hotcopy 目录整体还原。

十三、常见问题（FAQ）

Q1：访问项目路径返回 403 且不弹认证框？ tracd 只在 <环境名>/login 路径挂认证质询（见 8.5 排障实录），首次登录请访问 /myproject/login；若匿名权限已被移除，匿名直接 403 属预期行为。

Q2：pip 安装报 root 警告是否影响运行？ 不影响。该警告只是提示建议使用虚拟环境；系统级安装的 tracd 位于 /usr/local/bin/tracd。

Q3：htdigest 命令不存在？ 安装 apt install apache2-utils，或用 10.2 的 Python 方法直接生成哈希行（两者产物一致，已实测）。

Q4：多个项目怎么部署？ 同一父目录下 tracd -p 8140 -e /var/trac 自动发现全部环境，并自带项目列表首页；认证文件可用 --auth=* 通配应用到所有环境。

Q5：想换端口/只监听内网？ 端口与绑定地址是启动参数：--port、--hostname 127.0.0.1（仅本机）或 0.0.0.0（对外）。修改后需同步 systemd 单元并 daemon-reload。

十四、卸载与清理

systemctl disable --now tracd.service        # 停服务并取消自启（systemd 环境）
pip3 uninstall Trac                          # 卸载程序（jinja2/MarkupSafe 如无他用可一并卸载）
rm -rf /var/trac                             # 删除全部项目环境（含数据库，先确认备份）
rm -f /etc/systemd/system/tracd.service && systemctl daemon-reload

十五、参考链接

官方安装文档 TracInstall：https://trac.edgewall.org/wiki/TracInstall（查询日期 2026-10-31）
独立服务文档 TracStandalone：https://trac.edgewall.org/wiki/TracStandalone（查询日期 2026-10-31）
升级文档 TracUpgrade：https://trac.edgewall.org/wiki/TracUpgrade（查询日期 2026-10-31）
备份文档 TracBackup：https://trac.edgewall.org/wiki/TracBackup（查询日期 2026-10-31）
PyPI 项目页：https://pypi.org/project/Trac/（查询日期 2026-10-31）
站内相关：《Trac 1.6 介绍与选型指南》（选型与架构）、《Trac 1.6 配置参数详解》（trac.ini 逐项）、《Trac 1.6 常用 CLI 命令详解》（trac-admin/tracd 全参数）