Ubuntu 22.04 安装 Traq 3.8.6 指南

在 Ubuntu 22.04.5 LTS 上以 LEMP 形态安装 Traq v3.8.6 的全流程实测指南：Nginx+MariaDB+PHP 8.3 依赖安装、建库授权、发布包校验部署、Nginx 站点配置、安装向导四步与验证排障。

TraqTraqPHP 编程Ubuntu22.042026/10/28

Ubuntu 22.04 安装 Traq 3.8.6 指南

目标：在一台干净的 Ubuntu 22.04.5 LTS 服务器上，以 LEMP（Nginx + MariaDB + PHP-FPM 8.3）形态完成 Traq v3.8.6 的安装，覆盖「系统依赖 → 建库授权 → 部署程序包 → Nginx 站点 → 安装向导 → 验证」全流程。本篇所有命令与输出均为实测记录（实测日期 2026-10-28，实测环境 Ubuntu 22.04.5 LTS x86_64），仅个别依赖 systemd 的服务管理命令标注「预期结果」。

一、版本与环境说明

1.1 软件版本清单

组件实测版本获取方式
操作系统Ubuntu 22.04.5 LTS (Jammy Jellyfish) x86_64官方发行版
Nginxnginx/1.18.0 (Ubuntu)（包版本 1.18.0-6ubuntu14.22）Ubuntu 仓库
MariaDB10.6.23-MariaDB（包版本 1:10.6.23-0ubuntu0.22.04.1）Ubuntu 仓库
PHP-FPM8.3.36（包版本 8.3.36-1+ubuntu22.04.1+deb.sury.org+1）ppa:ondrej/php
Traqv3.8.6（2026-10-22 发布的最新稳定版）GitHub Releases

关于版本的三个事实（来源：GitHub 仓库 nirix/traq 与官方 README，查询日期 2026-10-28）：

  • Traq 官方 README 明确系统要求为 PHP 8.3+、MariaDB（或 MySQL）、Web 服务器需支持把请求路由到 index.php（Apache mod_rewrite 或等价配置）。Ubuntu 22.04 自带 PHP 8.1 不满足要求，因此本指南通过 ppa:ondrej/php 安装 PHP 8.3。
  • v3.9.0 目前仅发布到 alpha（v3.9.0-alpha.3，2026-10-26，标记为预发布），生产安装应选择最新稳定版 v3.8.6。
  • 项目处于活跃维护状态（主分支最近提交日期 2026-10-27，查询日期 2026-10-28）。

⚠️ 仓库地址说明：Traq 的官方网站为 https://traq.io ，官方 GitHub 仓库为 https://github.com/nirix/traq （作者 Jack Polgar / nirix）。网络上流传的 traq-dev/traq 地址已失效（实测返回 404），下载时认准 nirix/traq。

1.2 本指南约定

项约定值说明
服务器 IP192.168.1.100示例 IP，替换为你的服务器地址
Web 监听端口8143本指南约定端口，避免与 80 端口已有服务冲突；可按需改为 80/443
站点根目录/var/www/traqTraq 程序目录
数据库名 / 用户 / 密码traq / traq / q1w2e3r4示例值，生产环境请使用强密码
Traq 管理员admin / q1w2e3r4安装向导第 2 步创建

二、安装系统依赖

2.1 安装 Nginx 与 MariaDB

sudo apt-get update
sudo apt-get -y install nginx mariadb-server

实测安装完成后核对版本：

# nginx -v
nginx version: nginx/1.18.0 (Ubuntu)

# mysqladmin --version
mysqladmin  Ver 10.0 Distrib 10.6.23-MariaDB, for debian-linux-gnu on x86_64

2.2 安装 PHP 8.3 与所需扩展

Ubuntu 22.04 官方源只有 PHP 8.1，先添加 ondrej/php PPA（Ubuntu 社区维护的 PHP 多版本源）：

sudo apt-get -y install ca-certificates curl gnupg software-properties-common
sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update
sudo apt-get -y install php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-xml php8.3-curl php8.3-gd php8.3-zip

实测安装摘要（输出节选）：

Setting up php8.3-fpm (8.3.36-1+ubuntu22.04.1+deb.sury.org+1) ...
Setting up php8.3-mysql (8.3.36-1+ubuntu22.04.1+deb.sury.org+1) ...

核对 PHP 版本与关键扩展：

# php8.3 -v | head -1
PHP 8.3.36 (cli) (built: Oct 21 2026 14:31:50) (NTS)

# php8.3 -m | grep -Ei "pdo|mysql|mbstring|curl|gd|zip" | tr "\n" " "
curl gd mbstring mysqli mysqlnd PDO pdo_mysql zip

Traq 的 PDO 数据库驱动需要 pdo_mysql，其余为常见依赖（mbstring/curl/gd/zip），实测一个包覆盖全部需求，无需再单独装 Composer 等构建工具——v3.8.6 官方发布包内自带全部第三方依赖（详见第四章）。

2.3 启动服务并设置开机自启

Ubuntu 22.04 默认使用 systemd，标准管理命令如下（标准行为，预期结果标注）：

sudo systemctl enable --now nginx mariadb php8.3-fpm
# 预期结果：分别输出 "Synchronizing state of nginx.service with SysV service script..."
# 与 "Created symlink /etc/systemd/system/multi-user.target.wants/nginx.service → /usr/lib/systemd/system/nginx.service." 等

启动后确认服务监听就绪（实测；-p 需 root，可看到 nginx/php-fpm/mariadbd 进程名）：

# ss -ltn | grep -E ":(80|8143|3306)\b"
LISTEN 0      80         127.0.0.1:3306       0.0.0.0:*
LISTEN 0      511          0.0.0.0:8143       0.0.0.0:*
LISTEN 0      511             [::]:8143          [::]:*

三、准备数据库

MariaDB 默认 root 通过 unix_socket 本地免密登录，直接建库、建用户、授权：

sudo mysql

CREATE DATABASE traq CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'traq'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL PRIVILEGES ON traq.* TO 'traq'@'localhost';
FLUSH PRIVILEGES;
EXIT

说明：

  • Traq 的表自身使用 utf8mb4 建表（安装向导会执行内置 install.sql），库级默认值与其保持一致即可。
  • 向导中数据库主机填 127.0.0.1 走 TCP，或填 localhost 走 socket，两者在 MariaDB 10.6 下均可，本指南实测用 127.0.0.1。

四、部署 Traq 程序包

4.1 下载发布包并校验

从官方 GitHub Releases 下载 v3.8.6 的 tar.gz（官方由 CI 自动构建，同时提供 zip）：

cd /tmp
wget https://github.com/nirix/traq/releases/download/v3.8.6/traq-v3.8.6.tar.gz

校验完整性（官方 Release 资产页公布的 sha256 为 e440e01f5eff87bc6bec71f65fea4227905ff63e2b8a06029daa3ccd405d8c30，查询日期 2026-10-28）：

# ls -l traq-v3.8.6.tar.gz
-rw-r--r-- 1 root root 845361 Oct 28 10:25 traq-v3.8.6.tar.gz

# sha256sum traq-v3.8.6.tar.gz
e440e01f5eff87bc6bec71f65fea4227905ff63e2b8a06029daa3ccd405d8c30  traq-v3.8.6.tar.gz

哈希与官方一致。注意发布包体积只有约 825 KB——包内自带 vendor/ 目录（全部 PHP 第三方依赖），部署无需 Composer、无需 Node 构建，这是 Traq 相对多数 PHP 工程的一个省心点。

4.2 解压到站点根目录并设置权限

sudo mkdir -p /var/www/traq
sudo tar xzf traq-v3.8.6.tar.gz -C /var/www/traq
sudo chown -R www-data:www-data /var/www/traq

解压后的目录结构（实测）：

# ls -la /var/www/traq
total 80
drwxr-xr-x  6 www-data www-data  4096 Oct 22 16:35 .
drwxr-xr-x  4 root     root      4096 Oct 28 02:29 ..
-rw-r--r--  1 www-data www-data  1893 Oct 22 16:35 .gitlab-ci.yml
-rw-r--r--  1 www-data www-data 35821 Oct 22 16:35 COPYING
-rw-r--r--  1 www-data www-data  1027 Oct 22 16:35 README.md
-rw-r--r--  1 www-data www-data   380 Oct 22 16:35 TERMINATED_LICENCES.md
drwxr-xr-x  4 www-data www-data  4096 Oct 22 16:35 assets
-rw-r--r--  1 www-data www-data   380 Oct 22 16:35 htaccess.txt
-rw-r--r--  1 www-data www-data  1067 Oct 22 16:35 index.php
drwxr-xr-x  4 www-data www-data  4096 Oct 22 16:35 install
drwxr-xr-x  3 www-data www-data  4096 Oct 22 16:35 src
drwxr-xr-x 12 www-data www-data  4096 Oct 22 16:35 vendor

关键位置速记：

  • index.php：唯一前端入口；
  • install/：安装向导（含 install.sql 建库脚本与 upgrade.php 升级向导）；
  • vendor/traq/config/：Traq 自身配置目录（安装完成后在此生成 database.php，详见配置篇）；
  • htaccess.txt：Apache 环境才需要改名为 .htaccess，Nginx 环境用不到（第五章用 try_files 等价实现）。

五、配置 Nginx 站点

删除默认站点，写入 Traq 站点配置：

sudo rm -f /etc/nginx/sites-enabled/default
sudo tee /etc/nginx/sites-available/traq.conf > /dev/null <<'EOF'
server {
    listen 8143 default_server;
    listen [::]:8143 default_server;
    server_name _;
    root /var/www/traq;
    index index.php index.html;

    client_max_body_size 20m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ /\.(?!well-known) {
        deny all;
    }
}
EOF
sudo ln -sf /etc/nginx/sites-available/traq.conf /etc/nginx/sites-enabled/traq.conf

语法检查并重载（实测输出）：

# sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

# sudo systemctl reload nginx

原理说明：Traq 主应用（Avalon 框架）按 REQUEST_URI 解析路由，因此 try_files $uri $uri/ /index.php?$query_string; 这一条规则即可同时满足「静态资源直出」与「所有业务路径回落到 index.php」，不需要 PATH_INFO 之类的特殊配置。

六、运行安装向导

浏览器打开 http://192.168.1.100:8143/。此时 Traq 检测到尚无配置文件，会自动 302 跳转到安装向导。用命令行同样能看到这一行为（实测，安装前）：

# curl -sS -D - -o /dev/null http://127.0.0.1:8143/
HTTP/1.1 302 Found
Server: nginx/1.18.0 (Ubuntu)
Location: /install

6.1 第 0 步：许可协议

页面标题为 Traq Installation / License Agreement，正文展示 GPL-3.0 许可证全文，点击 Accept 进入下一步。

6.2 第 1 步：数据库信息

页面标题 Traq Installation / Step 1 - Database Details，按下表填写：

字段填写值说明
TypeMySQL可选 MySQL / SQLite / PostgreSQL
Server127.0.0.1数据库主机，表单默认值即为 127.0.0.1
Usernametraq第三章创建的数据库用户
Passwordq1w2e3r4数据库密码
Databasetraq数据库名
Prefixtraq_表前缀，留空亦可，默认建议 traq_

点击 Next。

6.3 第 2 步：管理员账号

页面标题 Traq Installation / Step 2 - Admin Account：

字段填写值
Usernameadmin
NameAdministrator
Passwordq1w2e3r4
Emailadmin@example.com

点击 Next。

6.4 第 3 步：完成

向导执行建表（执行 install/install.sql 并替换表前缀）、写入管理员账号与匿名用户、写入初始设置，最后生成配置文件，页面标题变为 Traq Installation / Complete，正文显示：

Installation Completed
You may now login.

配置文件由向导自动写入 vendor/traq/config/database.php，实测内容：

<?php
$db = array(
    'driver' => "pdo",
    'type' => "mysql",
    'host' => "127.0.0.1",
    'username' => "traq",
    'password' => "q1w2e3r4",
    'database' => "traq",
    'prefix' => "traq_",
);

若 vendor/traq/config/ 目录不可写，向导会改为在完成页直接展示这段配置代码，提示你手工保存为 vendor/traq/config/database.php——这就是「手动创建配置」的兜底路径，两种方式结果一致。

七、安装验证

7.1 数据表核对

向导共创建 24 张表（实测 SHOW TABLES 输出，前缀 traq_）：

# mysql -e "SHOW TABLES FROM traq;"
Tables_in_traq
traq_attachments
traq_components
traq_custom_field_values
traq_custom_fields
traq_milestones
traq_permissions
traq_plugins
traq_priorities
traq_project_roles
traq_projects
traq_settings
traq_severities
traq_statuses
traq_subscriptions
traq_ticket_history
traq_ticket_relationships
traq_tickets
traq_timeline
traq_types
traq_user_roles
traq_usergroups
traq_users
traq_wiki
traq_wiki_revisions

管理员账号写入 traq_users（实测）：

# mysql -N -e "SELECT id,username,group_id,email FROM traq.traq_users;"
1	admin	1	admin@example.com

group_id=1 即内置用户组 Administrators。

7.2 Web 三连验证

# curl -sSI http://127.0.0.1:8143/ | head -8
HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Wed, 28 Oct 2026 02:45:21 GMT
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Set-Cookie: PHPSESSID=kff28nl4emevd0m123tp22a9uu; path=/
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate

# curl -sSL http://127.0.0.1:8143/login | grep -o "<title>[^<]*"
<title>Login - Traq

登录实测：用 admin / q1w2e3r4 提交登录表单，返回 302 回首页，页面出现 admin 与 Logout，且页脚显示 Traq 3.8.6 版本号——三关（HTTP 200、登录 302、版本号落位）全部通过，安装完成。

八、排障实录

8.1 手工 POST 伪静态地址导致「空响应/循环跳转」

现象：脚本化安装时直接 curl -d "" http://服务器/install/step/1，收到空响应（重复请求则反复回到许可页）。

原因：安装向导的路由器（Nanite）按「PATH_INFO → 查询串」的顺序取路由，而向导表单的真实提交地址是 PHP_SELF 加查询串的形态，例如许可页表单的 action 实测为：

<form action="/install/index.php?/step/1" method="post">

直接 POST /install/step/1 会命中 Nginx 的 try_files 回落到根 index.php（主应用入口），主应用发现未安装又把请求重定向回 /install，形成「看似无响应」的循环。

解决：脚本化安装请向导式地按表单 action 提交，即 POST 到 /install/index.php?/step/1、/install/index.php?/step/2、/install/index.php?/step/3（保持同一 Cookie 会话）；浏览器操作不受影响，跟着页面点即可。

8.2 完成页提示「unable to create the config file」

现象：第 3 步完成后页面不显示 Completed，而是展示一段 PHP 代码并提示手工保存到 vendor/traq/config/database.php。

原因与解决：vendor/traq/config/ 目录对 PHP-FPM 运行用户不可写。执行 sudo chown -R www-data:www-data /var/www/traq 后按页面代码手工创建该文件即可；文件内容与向导自动生成的完全一致。

8.3 PHP 版本不满足导致依赖不可用

Ubuntu 22.04 默认源仅提供 PHP 8.1，低于官方要求的 8.3+，安装依赖或运行时会遇到兼容问题。解决：按 2.2 节走 ppa:ondrej/php 安装 php8.3-fpm，Nginx 的 fastcgi_pass 也必须指向 /run/php/php8.3-fpm.sock（8.3 版本的 socket 路径），不要沿用 8.1 的。

8.4 Apache 用户补充说明

若你使用 Apache 而非 Nginx：需要把程序目录下的 htaccess.txt 改名为 .htaccess（内容为把非静态请求重写到 index.php/$1），并启用 mod_rewrite。其余步骤（建库、向导）与本指南一致。

九、系列文档导航