Ubuntu 22.04 安装 Taiga 6.10 指南

Taiga 的单机源码部署是官方文档（docs.taiga.io《Install Taiga in Production》From source code 章节）给出的生产方案：PostgreSQL、RabbitMQ、Node.js 走系统包，taiga-back 从源码建 Python 虚拟环境，taiga-front-dist 拉取预编译产物由 Nginx 托管，四个自研服务全部交给 systemd。本文在 Ubuntu 22.04 LTS 服务器上完整走通该流程（back 6.10.2 / front-dist 6.10.3），所有命令与回显均为实测记录，途中踩到的三个坑（家目录权限、sudo 缺失、前端 tar.gz 失效）也一并还原。组件背景与选型逻辑见《Taiga 认知与选型：开源敏捷项目管理平台全景》，配置字段精讲见《Taiga 6.10 配置详解：五份配置文件逐段精讲》。

一、环境信息与版本

项目	值
操作系统	Ubuntu 22.04.5 LTS（Jammy Jellyfish）
架构	x86_64
主机名 / IP	taiga-lab / 10.89.73.10
对外入口	Nginx 80 端口（浏览器访问 http://10.89.73.10）
taiga-back	6.10.2（stable 分支，git describe 实测）
taiga-front-dist	6.10.3（stable 分支）
taiga-events / taiga-protected	6.10.0 / 6.10.1（stable 分支）
PostgreSQL	14.24（apt 默认；官方标注 <14，实测可用，见 10.1 节）
RabbitMQ / Node.js / Nginx	3.9.27 / 18.20.8 / 1.18.0
Python	3.10.12（系统自带）
演示账号	admin / q1w2e3r4

版本溯源说明（2026-10-28 查证）：官方文档旧版要求「下载 taiga-front release tar.gz」，该分发方式已失效——https://github.com/taigaio/taiga-front/releases/download/release-6.10.3/taiga-6.10.3.tgz 实测返回 404，仓库 Releases 列表为空。现行官方文档已改为 git clone taiga-front-dist 并检出 stable 分支，本文遵循现行口径。

二、安装系统依赖

2.1 基础编译与运行组件

sudo apt-get update
sudo apt-get install -y build-essential autoconf flex bison libjpeg-dev \
  libfreetype6-dev zlib1g-dev libzmq3-dev libgdbm-dev automake libtool \
  curl git gettext sudo
sudo apt-get install -y nginx rabbitmq-server redis-server

说明：官方命令清单里的 binutils-doc、tmux 等为可选文档/工具包，可省；sudo 在 Ubuntu 桌面版预装、最小化服务器版本可能缺失，官方流程后续全部依赖它，务必确认装上。

2.2 PostgreSQL 与 Python

sudo apt-get install -y postgresql postgresql-contrib postgresql-server-dev-14
sudo apt-get install -y python3 python3-pip python3-dev python3-venv \
  libxml2-dev libxslt-dev libssl-dev libffi-dev

官方写的是 postgresql-12 系列（Ubuntu 20.04 口径），Ubuntu 22.04 上对应包名为 postgresql-14，用元包 postgresql 亦可。postgresql-server-dev-14 提供 pg_config 与头文件，psycopg2 编译必需。

2.3 Node.js（taiga-events 专用）

官方脚本用 NodeSource 的 16.x，已过维护期，改用 18.x 实测通过：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

回显：

v18.20.8

2.4 启动基础服务并确认版本

sudo systemctl start postgresql rabbitmq-server redis-server nginx
psql --version && nginx -v && rabbitmqctl version

回显：

psql (PostgreSQL) 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)
nginx version: nginx/1.18.0 (Ubuntu)
3.9.27

三、创建运行用户与数据层

3.1 创建 taiga 系统用户

官方要求部署全程使用普通用户，禁止 root 直装：

sudo adduser --disabled-password --gecos "" taiga
sudo usermod -aG sudo taiga
sudo su - taiga

3.2 初始化 PostgreSQL

sudo -u postgres psql -c "CREATE USER taiga WITH PASSWORD 'q1w2e3r4';"
sudo -u postgres psql -c "CREATE DATABASE taiga OWNER taiga ENCODING 'utf8' TEMPLATE template0;"

回显：

CREATE ROLE
CREATE DATABASE

3.3 初始化 RabbitMQ

sudo rabbitmqctl add_user taiga q1w2e3r4
sudo rabbitmqctl add_vhost taiga
sudo rabbitmqctl set_permissions -p taiga taiga ".*" ".*" ".*"

回显（逐条）：

Adding user "taiga" ...
Adding vhost "taiga" ...
Setting permissions for user "taiga" in vhost "taiga" ...

官方提醒：数据库与 MQ 密码会出现在连接 URL 中，只应使用 a-z A-Z 0-9 - . _ ~ 等安全字符。

四、部署 taiga-back（API 后端）

4.1 拉取源码并建虚拟环境

cd ~
git clone https://github.com/taigaio/taiga-back.git taiga-back
cd taiga-back
git checkout stable
git log --oneline -1
git describe --tags
python3 -m venv .venv --prompt taiga-back
source .venv/bin/activate
pip install --upgrade pip wheel

回显（节选）：

4b023d8 chore: bump to 6.10.2 version
6.10.2
pip 26.2.2 from /home/taiga/taiga-back/.venv/lib/python3.10/site-packages/pip (python 3.10)

4.2 安装 Python 依赖

pip install -r requirements.txt

实测在 6 核主机、清华 PyPI 源下耗时 1 分 34 秒完成，无报错退出。若 psycopg2 编译失败，检查 2.2 节的 postgresql-server-dev-14 是否已装。

4.3 安装附件保护插件

pip install git+https://github.com/taigaio/taiga-contrib-protected.git@stable#egg=taiga-contrib-protected
pip show taiga-contrib-protected | head -3

回显：

Name: taiga-contrib-protected
Version: 6.10
Summary: The Taiga plugin for protected attachments

4.4 写配置文件

cp settings/config.py.prod.example settings/config.py

编辑 settings/config.py，至少修改以下五处（完整字段解析见配置详解篇）：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'taiga',
        'USER': 'taiga',
        'PASSWORD': 'q1w2e3r4',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

SECRET_KEY = "tk7vXq2mLp9wR4nZ8eYs3Ja6Hf1dC0ug"   # 自行生成随机串，events/protected 三处必须一致

TAIGA_SITES_SCHEME = "http"
TAIGA_SITES_DOMAIN = "10.89.73.10"
FORCE_SCRIPT_NAME = ""

EVENTS_PUSH_BACKEND_OPTIONS = {
    "url": "amqp://taiga:q1w2e3r4@127.0.0.1:5672/taiga"
}

CELERY_BROKER_URL = "amqp://taiga:q1w2e3r4@127.0.0.1:5672/taiga"

同时建议改两处：ENABLE_TELEMETRY = False（关闭遥测）、EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'（实验阶段邮件打到 stdout，避免 SMTP 报错）。

4.5 初始化数据库与管理员

source .venv/bin/activate
DJANGO_SETTINGS_MODULE=settings.config python manage.py migrate --noinput
CELERY_ENABLED=False DJANGO_SETTINGS_MODULE=settings.config \
  python manage.py createsuperuser
DJANGO_SETTINGS_MODULE=settings.config python manage.py loaddata initial_project_templates
DJANGO_SETTINGS_MODULE=settings.config python manage.py compilemessages
DJANGO_SETTINGS_MODULE=settings.config python manage.py collectstatic --noinput

实测回显（节选）：

  Applying wiki.0005_auto_20161201_1628... OK
Superuser created successfully.
Installed 2 object(s) from 1 fixture(s)
processing file djangojs.po in /home/taiga/taiga-back/.venv/lib/python3.10/site-packages/django/contrib/admin/locale/id/LC_MESSAGES
1008 static files copied to '/home/taiga/taiga-back/static'.

createsuperuser 交互中输入用户名 admin、邮箱 admin@example.com、密码 q1w2e3r4。migrate 全部完成后，数据库中建立 73 张业务表。

4.6 开发模式快速自检

DJANGO_SETTINGS_MODULE=settings.config python manage.py runserver

另开终端验证后立即 Ctrl+C 停掉：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/api/v1/

回显：

五、部署 taiga-front-dist（前端静态产物）

cd ~
git clone https://github.com/taigaio/taiga-front-dist.git taiga-front-dist
cd taiga-front-dist
git checkout stable
git describe --tags
cp dist/conf.example.json dist/conf.json

回显（节选）：

6.10.3

编辑 dist/conf.json，将 API 与 WebSocket 地址指向本机对外域名/IP（浏览器从外部访问，写 127.0.0.1 会白屏）：

{
    "api": "http://10.89.73.10/api/v1/",
    "eventsUrl": "ws://10.89.73.10/events",
    "baseHref": "/",
    ...
}

六、部署 taiga-events（WebSocket 网关）

cd ~
git clone https://github.com/taigaio/taiga-events.git taiga-events
cd taiga-events
git checkout stable
npm install
cp .env.example .env

npm install 在 Node 18.20.8 下实测无报错。编辑 .env：

RABBITMQ_URL="amqp://taiga:q1w2e3r4@127.0.0.1:5672/taiga"
WEB_SOCKET_SERVER_PORT=8888
APP_PORT=3023
SECRET="tk7vXq2mLp9wR4nZ8eYs3Ja6Hf1dC0ug"

SECRET 必须与 taiga-back config.py 的 SECRET_KEY 完全一致，否则前端登录后 WebSocket 鉴权失败、看板无法实时刷新。

七、部署 taiga-protected（附件保护）

cd ~
git clone https://github.com/taigaio/taiga-protected.git taiga-protected
cd taiga-protected
git checkout stable
python3 -m venv .venv --prompt taiga-protected
source .venv/bin/activate
pip install --upgrade pip wheel
pip install -r requirements.txt
cp env.sample .env

编辑 .env（注意此文件键值无引号）：

SECRET_KEY=tk7vXq2mLp9wR4nZ8eYs3Ja6Hf1dC0ug
MAX_AGE=300
TAIGA_SUBPATH=

同样，SECRET_KEY 三处一致是硬约束。

八、systemd 托管四个服务

按官方模板创建 /etc/systemd/system/taiga.service：

[Unit]
Description=taiga_back
After=network.target

[Service]
User=taiga
WorkingDirectory=/home/taiga/taiga-back
ExecStart=/home/taiga/taiga-back/.venv/bin/gunicorn --workers 4 --timeout 60 --log-level=info --access-logfile - --bind 0.0.0.0:8001 taiga.wsgi
Restart=always
RestartSec=3

Environment=PYTHONUNBUFFERED=true
Environment=DJANGO_SETTINGS_MODULE=settings.config

[Install]
WantedBy=default.target

/etc/systemd/system/taiga-async.service：

[Unit]
Description=taiga_async
After=network.target

[Service]
User=taiga
WorkingDirectory=/home/taiga/taiga-back
ExecStart=/home/taiga/taiga-back/.venv/bin/celery -A taiga.celery worker -B --concurrency 4 -l INFO
Restart=always
RestartSec=3
ExecStop=/bin/kill -s TERM $MAINPID

Environment=PYTHONUNBUFFERED=true
Environment=DJANGO_SETTINGS_MODULE=settings.config

[Install]
WantedBy=default.target

/etc/systemd/system/taiga-events.service：

[Unit]
Description=taiga_events
After=network.target

[Service]
User=taiga
WorkingDirectory=/home/taiga/taiga-events
ExecStart=/usr/bin/npm run start:production
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

注意：官方模板写的是 ExecStart=npm run start:production，systemd 非登录环境下 PATH 不含 /usr/bin 时会启动失败，用绝对路径最稳。

/etc/systemd/system/taiga-protected.service：

[Unit]
Description=taiga_protected
After=network.target

[Service]
User=taiga
WorkingDirectory=/home/taiga/taiga-protected
ExecStart=/home/taiga/taiga-protected/.venv/bin/gunicorn --workers 4 --timeout 60 --log-level=info --access-logfile - --bind 0.0.0.0:8003 server:app
Restart=always
RestartSec=3

Environment=PYTHONUNBUFFERED=true

[Install]
WantedBy=default.target

启动并设开机自启：

sudo systemctl daemon-reload
sudo systemctl enable --now taiga taiga-async taiga-events taiga-protected
systemctl is-active taiga taiga-async taiga-events taiga-protected

回显：

active
active
active
active

确认监听端口：

ss -ltn | grep -E ':8001|:8003|:8888'

回显：

LISTEN 0      2048         0.0.0.0:8001       0.0.0.0:*
LISTEN 0      2048         0.0.0.0:8003       0.0.0.0:*
LISTEN 0      511                *:8888             *:*

九、Nginx 接入与端到端验证

9.1 站点配置

移除默认站点，创建 /etc/nginx/conf.d/taiga.conf（HTTP 实验版；生产请按官方模板加 443 与 TLS）：

server {
    listen 80 default_server;
    server_name _;

    large_client_header_buffers 4 32k;
    client_max_body_size 50M;
    charset utf-8;

    access_log /home/taiga/logs/nginx.access.log;
    error_log /home/taiga/logs/nginx.error.log;

    # Frontend
    location / {
        alias /home/taiga/taiga-front-dist/dist/;
        index index.html;
        try_files $uri $uri/ index.html =404;
    }

    # API
    location /api/ {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8001/api/;
        proxy_redirect off;
    }

    # Admin
    location /admin/ {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8001/admin/;
        proxy_redirect off;
    }

    # Static files
    location /static/ {
        alias /home/taiga/taiga-back/static/;
    }

    # Media（受保护附件）
    location /_protected/ {
        internal;
        alias /home/taiga/taiga-back/media/;
        add_header Content-disposition "attachment";
    }

    location /media/exports/ {
        alias /home/taiga/taiga-back/media/exports/;
        add_header Content-disposition "attachment";
    }

    location /media/ {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8003/;
        proxy_redirect off;
    }

    # Events（WebSocket）
    location /events {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;
        proxy_pass http://127.0.0.1:8888/events;
    }
}

先建日志目录再启动：

mkdir -p /home/taiga/logs && sudo chown taiga:taiga /home/taiga/logs
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl restart nginx

回显：

nginx: configuration file /etc/nginx/nginx.conf test is successful

9.2 排障实录：首页 404（Permission denied）

首次访问 http://10.89.73.10/ 返回 404（162 字节错误页），而 /api/v1/ 一切正常。查 Nginx 错误日志：

tail -3 /home/taiga/logs/nginx.error.log

回显：

2026/10/28 02:03:23 [crit] 11619#11619: *1 stat() "/home/taiga/taiga-front-dist/dist/" failed (13: Permission denied), client: 127.0.0.1, server: _, request: "GET / HTTP/1.1", host: "127.0.0.1"

根因：adduser 在 Ubuntu 上默认创建 750 权限的家目录（drwxr-x--- taiga taiga），Nginx worker 以 www-data 运行，无法穿越 /home/taiga。修复：

ls -ld /home/taiga          # 确认当前权限
chmod 755 /home/taiga       # 放行其他用户进入（不递归，仅目录本身）

回显（修复前后对比）：

drwxr-x--- 10 taiga taiga 4096 Oct 28 02:02 /home/taiga
drwxr-xr-x 10 taiga taiga 4096 Oct 28 02:02 /home/taiga

复测：

curl -s -o /tmp/idx.html -w '%{http_code} %{size_download}\n' http://127.0.0.1/
grep -o '<title>[^<]*</title>' /tmp/idx.html

回显：

200 140629
<title>Taiga</title>

这是本机部署 Taiga 命中率最高的坑：官方文档假设家目录可被 Nginx 读取但未提示权限细节。若你把 front-dist 放在 /opt 等公共路径则不会遇到。

9.3 登录与功能闭环验证

API 登录（normal 类型）：

curl -s -X POST http://127.0.0.1/api/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{"type":"normal","username":"admin","password":"q1w2e3r4"}' \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("auth_token:", d["auth_token"][:20]+"..."); print("username:", d["username"], "| email:", d["email"])'

回显：

auth_token: eyJhbGciOiJIUzI1NiIs...
username: admin | email: admin@example.com

携带令牌建项目：

TOKEN=<上一步的 auth_token>
curl -s -X POST http://127.0.0.1/api/v1/projects \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Lab Demo","description":"end-to-end test","creation_template":1}' \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("id:", d.get("id"), "| slug:", d.get("slug"))'

回显：

id: 1 | slug: lab-demo

WebSocket 通道（/events 经 Nginx 升级）：

curl -s -i --max-time 3 -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==' -H 'Sec-WebSocket-Version: 13' \
  http://127.0.0.1/events | head -3

回显：

HTTP/1.1 101 Switching Protocols
Server: nginx/1.18.0 (Ubuntu)
Date: Wed, 28 Oct 2026 02:04:10 GMT

静态文件与 Django Admin：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/static/emails/logo-web.png
curl -s -o /dev/null -w '%{http_code}\n' -L http://127.0.0.1/admin/

回显：

200
200

异步链路：建项目动作触发 celery 任务，journalctl 可见：

Oct 28 02:04:35 taiga-lab celery[11412]: [2026-10-28 02:04:35,896: INFO/MainProcess] Task taiga.timeline.service.push_to_timelines[8cc0bad0-da18-407e-8a54-0a55d03595de] received
Oct 28 02:04:41 taiga-lab celery[11593]: [2026-10-28 02:04:41,187: INFO/Beat] Scheduler: Sending due task send-bulk-emails (taiga.projects.notifications.tasks.send_bulk_email)

十、安装验证清单与已知口径差异

10.1 验证清单

检查项	命令	期望
四服务 active	`systemctl is-active taiga taiga-async taiga-events taiga-protected`	四个 active
首页	`curl -I http://10.89.73.10/`	200，title 为 Taiga
API 探活	`curl http://127.0.0.1/api/v1/`	JSON 端点列表
登录	POST /api/v1/auth	返回 auth_token
WebSocket	Upgrade 握手	101 Switching Protocols
静态资源	/static/ 路径	200
数据表	psql 查 pg_tables	73 张

10.2 与官方文档的口径差异（实测结论）

PostgreSQL 14 可用：官方标注 <14（文档停留在 Ubuntu 20.04 时代），实测 PG 14.24 迁移、读写、看板操作全部正常。属于超口径使用，升级前建议自测。
前端 tar.gz 已失效：官方旧版安装文档的 release 压缩包地址 404，现行做法是 git clone taiga-front-dist 检出 stable。
Node 16 → 18：官方脚本用 16.x（已 EOL），18.20.8 实测 taiga-events 的 npm install 与运行无异常。
Redis 非必需：taiga-back 默认 LocMemCache，不依赖 Redis 服务；装与不装均可。
sudo 必须确认存在：最小化系统缺 sudo 会导致 3.1 节之后的全部命令不可用。

安装完成后，日常使用的配置细节转入《Taiga 6.10 配置详解：五份配置文件逐段精讲》，运维与排障转入《Taiga 6.10 运维命令手册：服务、备份与排障》。