Trac 1.4 版安装指南

Trac 使用 Python 编程语言编写，需要一个数据库，例如 ​SQLite、​PostgreSQL 或 ​MySQL。对于 HTML 渲染，Trac 使用 ​Jinja2 模板系统，尽管 Trac 1.5.1 之前仍支持 Genshi 模板。

Trac 也支持本地化，并且可能已有您语言的翻译版本。如果您希望使用其他语言的 Trac 界面，请确保已安装可选包 Babel。请注意下面 安装 Trac 部分中本地化支持的额外步骤。如果缺少 Babel，您将只能获得默认的英文版本。

如果您有兴趣为其他语言贡献新翻译或改进现有翻译，请查阅 ​TracL10N。

以下是安装和设置 Trac 的通用说明。虽然您可以在 ​TracInstallPlatforms 上找到在特定系统上安装 Trac 的说明，但请首先通读这些通用说明，以便充分理解所涉及的任务。

安装步骤

1. 依赖项
   1. 强制性依赖项
   2. 可选依赖项
2. 安装 Trac
   1. 使用 pip
   2. 使用安装程序
   3. 使用包管理器
3. 创建项目环境
4. 部署 Trac
   1. 运行独立服务器
   2. 在 Web 服务器上运行 Trac
5. 配置身份验证
6. 授予管理员用户管理权限
7. 配置 Trac
8. 使用 Trac

依赖项

强制性依赖项

要安装 Trac，必须安装以下软件包

• ​Python，版本 >= 2.7 且 < 3.0（请注意，此版本已放弃对 Python 2.6 的支持）
• ​setuptools，版本 >= 0.6
• ​Jinja2，版本 >= 2.9.3

Setuptools 警告：如果您的 setuptools 版本在 5.4 到 5.6 之间，则必须设置环境变量 PKG_RESOURCES_CACHE_ZIP_MANIFESTS 以避免显著的性能下降。更多信息可在 部署 Trac 中找到。

您还需要一个数据库系统和相应的 Python 绑定。数据库可以是 SQLite、PostgreSQL 或 MySQL。

对于 SQLite 数据库

Python 标准发行版中已捆绑 SQLite 数据库绑定（即 sqlite3 模块）。

或者，您可以安装比 Python 发行版提供的版本更新的 ​pysqlite。有关详细信息，请参阅 ​PySqlite。

对于 PostgreSQL 数据库

您需要安装数据库及其 Python 绑定

• ​PostgreSQL，版本 9.1 或更高
• ​psycopg2，版本 2.0 或更高

有关详细信息，请参阅 ​DatabaseBackend。

对于 MySQL 数据库

Trac 与 MySQL 配合良好，前提是您使用以下组件

• ​MySQL，版本 5.0 或更高
• ​PyMySQL

考虑到 MySQL 周围的注意事项和已知问题，在创建数据库之前，请仔细阅读 ​MySqlDb 页面。

可选依赖项

Subversion

​Subversion，版本 1.6.x 或更高，以及对应的 Python 绑定。

有适用于各种平台的​预编译 SWIG 绑定。有关更多信息，请参阅 ​获取 Subversion。

注意

• Trac 不使用 ​PySVN，也不支持较新的 ctype 风格绑定。
• 如果使用 Subversion，Trac 必须安装在同一台机器上。不支持远程仓库（​不支持）。

有关故障排除信息，请参阅 ​TracSubversion 页面。

Git

支持 ​Git 1.5.6 或更高版本。更多信息可在 ​TracGit 页面找到。

其他版本控制系统

对其他版本控制系统的支持通过第三方插件提供。请参阅 ​PluginList#VersionControlSystems 和 ​VersionControlSystem。

Web 服务器

Web 服务器是可选的，因为 Trac 随附一个服务器，请参阅下面 运行独立服务器 部分。

或者，您可以将 Trac 配置为在以下任何环境中运行

• 带有 ​Apache 的
  • ​mod_wsgi，请参阅 TracModWSGI 和 ​ModWSGI IntegrationWithTrac。
  • ​mod_python 3.5.0，请参阅 TracModPython
• 支持 ​FastCGI 的 Web 服务器（请参阅 TracFastCgi）
• 支持 ​AJP 的 Web 服务器（请参阅 ​TracOnWindowsIisAjp）
• 带有 FastCGI 和 FastCGI 到 WSGI 网关的 Microsoft IIS（请参阅 ​带有 FastCGI 的 IIS）
• 支持 CGI 的 Web 服务器（请参阅 TracCgi），但不推荐将 Trac 用作 CGI 脚本，最好使用前面的选项之一。

其他 Python 包

• ​Babel，版本 0.9.6 或 >= 1.3，本地化支持所需
• ​pytz 以获取完整时区列表，否则 Trac 将回退到内部时区实现的较短列表。安装 Babel 将同时安装 pytz。
• ​docutils，版本 >= 0.3.9，用于 WikiRestructuredText。
• ​Pygments，用于语法高亮。
• ​Textile，用于渲染 ​Textile 标记语言。
• Windows 上使用 ​passlib 以解码除 SHA-1 之外的 htpasswd 格式。
• Windows 上使用 ​pyreadline 以实现 trac-admin 命令补全。

注意：这些依赖项的可用版本不一定可互换，因此请注意版本号。如果您在让 Trac 工作时遇到问题，请在向 ​邮件列表 或 ​IRC 频道 寻求帮助之前，仔细检查所有依赖项。

请参阅这些包的文档，了解它们的最佳安装方式。此外，大多数 ​特定平台说明 也描述了依赖项的安装。但请记住，其中的信息可能涉及比您正在安装的 Trac 版本更旧的版本。

安装 Trac

用于创建和维护项目环境的 trac-admin 命令行工具以及 tracd 独立服务器随 Trac 一同安装。安装 Trac 有多种方法。

本指南假定您拥有 root 用户的高级权限或通过在命令前加上 sudo。在基于 Unix 的平台上进行典型安装时，应使用 umask 0002。

使用 pip

pip 是现代的 Python 包管理器，包含在 Python 2.7.9 及更高版本中。对于更早的 Python 版本，请使用 ​get-pip.py 安装 pip。

$ pip install Trac

pip 将自动解决所需依赖项（Jinja2 和 setuptools），并从 pypi.org 下载最新包。

您也可以直接从源包安装。您可以从 ​TracDownload 页面获取 tar 或 zip 格式的源代码。解压存档后，切换到包含 setup.py 的目录并运行

$ pip install .

pip 支持许多其他安装机制。它可以传递存档的 URL 或其他下载位置。以下是一些示例

• 从 zip 存档安装最新的稳定版本

  $ pip install https://download.edgewall.org/trac/Trac-latest.zip
  

• 从 tar 存档安装最新的开发版本

  $ pip install https://download.edgewall.org/trac/Trac-latest-dev.tar.gz
  

• 从 Subversion 安装未发布的 1.2 稳定版

  $ pip install svn+https://svn.edgewall.org/repos/trac/branches/1.2-stable
  

• 安装最新的开发预览版（不建议用于生产环境安装）

  $ pip install --find-links=https://trac.edgewall.org/wiki/TracDownload Trac
  

可以使用 pip 从 PyPI 安装可选依赖项

$ pip install babel docutils pygments textile

可选依赖项也可以使用 setup 文件中的 extras 键来指定

$ pip install Trac[babel,rest,pygments,textile]

rest 是安装 docutils 依赖项的额外项。

如果使用 MySQL 或 PostgreSQL 数据库，请在列表中包含 mysql 或 psycopg2-binary。

此外，您可以使用 pip 从 PyPI 安装多个 Trac 插件（​此处列出）。有关更多信息，请参阅 TracPlugins。

使用安装程序

在 Windows 上，Trac 可以使用 ​TracDownload 页面上提供的 exe 安装程序进行安装。安装程序适用于 32 位和 64 位版本的 Python。请确保使用与您的 Python 安装架构匹配的安装程序。

使用包管理器

Trac 可能在您平台的包仓库中可用。但是，您的包管理器可能不提供 Trac 的最新版本。

创建项目环境

一个 Trac 环境是 Trac 存储维基页面、票据、报告、设置等信息的后端。一个环境是一个目录，包含一个人类可读的配置文件以及其他文件和目录。

使用 trac-admin 创建新环境

$ trac-admin /path/to/myproject initenv

trac-admin 将提示您提供创建环境所需的信息：项目名称和数据库连接字符串。如果您不确定这些选项中应指定什么，只需按 <Enter> 使用默认值。

只要您安装了 SQLite，使用默认的数据库连接字符串就始终有效。对于其他 ​数据库后端，您应该提前计划并在此刻准备好一个可用的数据库。

另请注意，您在此处指定的值稍后可以使用 TracAdmin 或直接编辑 conf/trac.ini 配置文件进行更改。

最后，确保 Web 前端运行的用户帐户对环境目录及其所有文件都具有写入权限。如果您以该用户身份运行 trac-admin ... initenv，则会是这种情况。如果不是，您应该在之后设置正确的用户。例如在 Linux 上，如果 Web 服务器以用户 apache 和组 apache 运行，请输入

$ chown -R apache:apache /path/to/myproject

Apache 服务器的实际用户名和组名可能不完全是 apache，它们在 Apache 配置文件中由 User 和 Group 指令指定（如果您使用 Apache httpd）。

警告：帐户名和项目路径请仅使用 ASCII 字符，不支持 Unicode 字符。

部署 Trac

Setuptools 警告：如果您的 setuptools 版本在 5.4 到 5.6 之间，则必须设置环境变量 PKG_RESOURCES_CACHE_ZIP_MANIFESTS 以避免显著的性能下降。

如果运行 tracd，环境变量可以设置为系统范围有效，或者仅对运行 tracd 进程的用户有效。除了此处讨论的方法外，还有多种方法可以实现这一点，具体取决于您的操作系统发行版。

要使环境变量在系统范围内生效，可以将包含 export 语句的 shell 脚本添加到 /etc/profile.d。要对用户会话生效，可以将 export 语句添加到 ~/.profile。

export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1

或者，可以在执行 tracd 之前在 shell 中设置变量

$ PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject

如果运行 Apache Web 服务器，Ubuntu/Debian 用户应将 export 语句添加到 /etc/apache2/envvars。RedHat/CentOS/Fedora 用户可以将 export 语句添加到 /etc/sysconfig/httpd。

运行独立服务器

创建 Trac 环境后，您可以通过运行独立服务器 tracd 轻松试用 Web 界面

$ tracd --port 8000 /path/to/myproject

然后，打开浏览器并访问 https://:8000/。您应该会看到 tracd 所知的所有环境的简单列表。点击您刚创建的环境链接，您应该能看到 Trac 正在运行。如果您只计划使用 Trac 管理单个项目，则可以通过以下方式启动独立服务器来跳过环境列表

$ tracd -s --port 8000 /path/to/myproject

在 Web 服务器上运行 Trac

Trac 提供了连接到“真实”Web 服务器的各种选项

• FastCGI
• 带 mod_wsgi 的 Apache
• 带 mod_python 的 Apache
• CGI （不应使用，因为性能远非最佳）

Trac 还支持 ​AJP，如果您想连接到 IIS，这可能是您的选择。其他部署场景也是可能的：​nginx、​uwsgi、​Isapi-wsgi 等。

生成 Trac cgi-bin 目录

CGI、FastCGI 和 mod-wsgi 的应用程序脚本可以使用 trac-admin 的 deploy 命令生成

deploy <directory>

    Extract static resources from Trac and all plugins

授予 Web 服务器对 cgi-bin 目录中脚本的执行权限。

例如，以下是一个典型的目录结构

$ mkdir -p /var/trac
$ trac-admin /var/trac/<project> initenv
$ trac-admin /var/trac/<project> deploy /var/www
$ ls /var/www
cgi-bin htdocs
$ chmod ugo+x /var/www/cgi-bin/*

映射静态资源

如果没有额外配置，Trac 将处理对样式表和图像等静态资源的请求。对于除 TracStandalone 部署之外的任何情况，这都不是最佳选择，因为 Web 服务器可以直接提供静态资源。对于 CGI 设置，这非常不理想，因为它会导致极差的性能。

诸如 ​Apache 等 Web 服务器允许您为资源创建别名，赋予它们一个不一定反映其在文件系统上位置的虚拟 URL。我们可以将静态资源的请求直接映射到文件系统上的目录，以避免 Trac 处理这些请求。

静态资源有两个主要 URL 路径：/chrome/common 和 /chrome/site。插件可以添加自己的资源，通常可通过 /chrome/<plugin> 路径访问。

如果为所有插件提取了静态资源，则可以使用单个 /chrome 别名。这意味着在安装或更新提供静态资源的插件后，或在修改 $env/htdocs 目录中的资源后，必须执行 deploy 命令（在上一节中讨论）。这可能适用于大多数安装，但如果例如您希望通过插件管理页面上传插件，这可能不是您想要的。

deploy 命令会创建一个包含以下内容的 htdocs 目录

• common/ - Trac 的静态资源
• site/ - 环境的 htdocs/ 目录的副本
• shared - 多个 Trac 环境共享的静态资源，其位置由 [inherit] htdocs_dir 选项定义
• <plugin>/ - 此环境中启用插件提供的每个资源目录的对应目录

下面的示例将创建一个单独的 /chrome 别名。如果这不适合您的安装，您只需创建更具体的别名

Alias /trac/chrome/common /path/to/trac/htdocs/common
Alias /trac/chrome/site /path/to/trac/htdocs/site
Alias /trac/chrome/shared /path/to/trac/htdocs/shared
Alias /trac/chrome/<plugin> /path/to/trac/htdocs/<plugin>

示例：Apache 和 ScriptAlias

假设部署已按此方式完成

$ trac-admin /var/trac/<project> deploy /var/www

将以下片段添加到 Apache 配置中，并更改路径以匹配您的部署。该片段必须放在 ScriptAlias 或 WSGIScriptAlias 指令之前，因为这些指令会将所有请求映射到 Trac 应用程序

Alias /trac/chrome /path/to/trac/htdocs

<Directory "/path/to/www/trac/htdocs">
  # For Apache 2.2
  <IfModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
  </IfModule>
  # For Apache 2.4
  <IfModule mod_authz_core.c>
    Require all granted
  </IfModule>
</Directory>

如果使用 mod_python，也请添加此项，否则别名将被忽略

<Location "/trac/chrome/common">
  SetHandler None
</Location>

或者，如果您希望直接从项目的 htdocs 目录提供静态资源，而不是从 deploy 命令提取文件的位置提供，则可以配置 Apache 来提供这些资源。同样，将其放在 .*cgi 脚本的 ScriptAlias 或 WSGIScriptAlias 之前，并调整名称和位置以匹配您的安装

Alias /trac/chrome/site /path/to/projectenv/htdocs

<Directory "/path/to/projectenv/htdocs">
  # For Apache 2.2
  <IfModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
  </IfModule>
  # For Apache 2.4
  <IfModule mod_authz_core.c>
    Require all granted
  </IfModule>
</Directory>

别名 /trac/chrome/common 的另一个替代方案是让 Trac 为这些（且仅这些）静态资源生成直接链接，使用 trac.htdocs_location 配置设置

[trac]
htdocs_location = http://static.example.org/trac-common/

请注意，这使得拥有一个专用域来提供这些静态资源变得容易，最好是无 Cookie 的。

当然，您仍然需要通过 Web 服务器在指定的 URL 上使 Trac htdocs/common 目录可用，例如通过将该目录复制（或链接）到 Web 服务器的文档根目录中

$ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common

设置插件缓存

某些 Python 插件需要提取到缓存目录。默认情况下，缓存位于当前用户的主目录中。当在 Web 服务器上以没有主目录的专用用户身份运行 Trac 时（强烈推荐此做法），这可能会阻止插件启动。要覆盖缓存位置，您可以设置 PYTHON_EGG_CACHE 环境变量。有关如何设置环境变量的详细说明，请参阅您的服务器文档。

配置身份验证

Trac 使用 HTTP 身份验证。您需要配置您的 Web 服务器，以便在访问 .../login URL（“登录”按钮的虚拟路径）时请求身份验证。提供凭据后，Trac 将自动获取 REMOTE_USER 变量。因此，所有用户管理都通过您的 Web 服务器配置进行。请查阅您的 Web 服务器文档以获取更多信息。

用于身份验证的用户帐户的添加、删除和配置过程取决于您运行 Trac 的具体方式。

请参阅以下部分之一

• 如果您使用独立服务器 tracd，请参阅 TracStandalone#UsingAuthentication。
• 如果您使用 Apache Web 服务器及其任何前端：mod_wsgi、mod_python、mod_fcgi 或 mod_fastcgi，请参阅 TracModWSGI#ConfiguringAuthentication。
• 如果您使用其他支持 FCGI 的 Web 服务器（Cherokee、Lighttpd、LiteSpeed、nginx），请参阅 TracFastCgi。

​TracAuthenticationIntroduction 也包含一些对初学者有用的信息。

授予管理员用户管理权限

授予用户管理员权限

$ trac-admin /path/to/myproject permission add admin TRAC_ADMIN

该用户将拥有一个管理导航项，可直接跳转到管理 Trac 项目的页面。

配置 Trac

配置选项记录在 TracIni 页面上。

TracRepositoryAdmin 提供了有关为您的项目配置版本控制仓库的信息。

除了可选的版本控制后端，Trac 还提供了几个默认禁用的可选功能

• 细粒度权限策略
• 自定义权限
• 票据删除
• 票据克隆
• 票据变更集引用

使用 Trac

一旦您的 Trac 站点启动并运行，您就应该能够创建票据、查看时间线、浏览（如果已配置）您的版本控制仓库等。

请记住，默认情况下，匿名（未登录）用户只能访问少数功能，特别是他们将对资源具有只读访问权限。您需要配置身份验证并向已通过身份验证的用户授予额外的权限才能查看所有功能。

祝您使用愉快！

​Trac 团队

---

另请参阅：​TracInstallPlatforms、TracGuide、TracUpgrade