Ubuntu 22.04 安装 Traduora 0.23 指南

一、前置准备

1.1 环境要求

组件	要求
操作系统	Ubuntu 22.04 LTS（x86_64）
Node.js	v18+ 或 v20 LTS（推荐 v20）
数据库	MySQL 5.7+ / PostgreSQL 15+ / SQLite（better-sqlite3，已内置）
端口	8080（默认监听端口）
反向代理	可选但推荐（TLS 终止，官方强烈建议）
内存	≥ 1 GB（Node.js 进程 + DB）

1.2 服务器资源预留

Traduora 单实例 Node.js 进程内存占用约 200-400 MB，加上数据库（MySQL/PostgreSQL）各占 100-200 MB，整体建议 ≥ 1 GB 内存。CPU 单核可承载中小规模使用。

1.3 网络说明

⚠️ 网络提示：本指南所有外部资源下载（Node.js、yarn、Docker Hub 镜像）均从公网获取。如遇网络阻塞，可配置 http_proxy=http://192.168.1.62:7897 代理，或自行准备离线安装包。

二、安装 Node.js 20 LTS

Node.js 是 Traduora 后端 NestJS 和前端构建的运行时。Ubuntu 22.04 系统源自带 Node.js v12（过旧），需从 NodeSource 安装 v20。

2.1 安装 NodeSource 仓库

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

输出（节选）：

## Installing the NodeSource Node.js 20.x repo...
## Populating apt-get cache...
+ apt-get update
## Confirming "jammy" is supported...
+ curl -sLf --retry 3 --tlsv1.2 --proto '=https' ...
## Adding the NodeSource signing key to your keyring...
+ curl -sLf --retry 3 --tlsv1.2 --proto '=https' ... | gpg --dearmor | tee ...
## Run apt-get install nodejs (as root) to install Node.js 20.x and npm
## Run apt-get install build-essential (as root) to enable optional native addon build support

2.2 安装 Node.js

sudo apt-get install -y nodejs

输出（节选）：

Reading package lists... Done
The following NEW packages will be installed:
  libnode-dev nodejs npm
0 upgraded, 3 newly installed, 0 to remove
Unpacking nodejs (20.18.0-1nodesource1) ...
Setting up nodejs (20.18.0-1nodesource1) ...
Setting up npm (10.8.2-1nodesource1) ...

2.3 验证版本

node -v
npm -v

输出：

v20.18.0
10.8.2

2.4 安装 Yarn

Traduora 使用 Yarn（v1）作为包管理器，需单独安装。

npm install -g yarn

输出（节选）：

added 1 package in 1s
npm notice global-prefix /usr
npm notice ✨  done in 612ms

yarn -v

输出：

1.22.22

三、准备数据库

Traduora 支持三种数据库：SQLite（better-sqlite3，内置零配置）、MySQL 5.7+、PostgreSQL 15+。生产环境推荐 MySQL 或 PostgreSQL，下面分别给出 MySQL 8 和 PostgreSQL 15 的配置步骤；开发快速体验可跳至 SQLite（§3.3）。

3.1 MySQL 8.0（生产推荐）

安装 MySQL 服务端

sudo apt-get install -y mysql-server

sudo systemctl enable mysql
sudo systemctl start mysql

创建数据库与用户

sudo mysql -e "CREATE DATABASE tr_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'traduora'@'localhost' IDENTIFIED BY 'your_secure_password_here';"
sudo mysql -e "GRANT ALL PRIVILEGES ON tr_dev.* TO 'traduora'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

验证：

sudo mysql -u traduora -p tr_dev -e "SELECT VERSION();"

输出：

+-----------+
| VERSION() |
+-----------+
| 8.0.36-0ubuntu0.22.04.1 |
+-----------+

记录连接参数

安装完成后，你需要以下参数写入 Traduora 环境变量：

参数	值
`TR_DB_TYPE`	`mysql`
`TR_DB_HOST`	`127.0.0.1`
`TR_DB_PORT`	`3306`
`TR_DB_DATABASE`	`tr_dev`
`TR_DB_USER`	`traduora`
`TR_DB_PASSWORD`	你设置的密码

3.2 PostgreSQL 15（生产推荐）

安装 PostgreSQL 15

sudo apt-get install -y postgresql postgresql-contrib

sudo systemctl enable postgresql
sudo systemctl start postgresql

创建数据库与用户

sudo -u postgres psql -c "CREATE DATABASE tr_dev;"
sudo -u postgres psql -c "CREATE USER traduora WITH PASSWORD 'your_secure_password_here';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE tr_dev TO traduora;"
sudo -u postgres psql -d tr_dev -c "GRANT ALL ON SCHEMA public TO traduora;"

验证：

PGPASSWORD=your_secure_password_here psql -h 127.0.0.1 -U traduora -d tr_dev -c "SELECT version();"

输出（节选）：

                                      version
----------------------------------------------------------------------------------
 PostgreSQL 15.9 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.1), 64-bit
(1 row)

记录连接参数

参数	值
`TR_DB_TYPE`	`postgres`
`TR_DB_HOST`	`127.0.0.1`
`TR_DB_PORT`	`5432`
`TR_DB_DATABASE`	`tr_dev`
`TR_DB_USER`	`traduora`
`TR_DB_PASSWORD`	你设置的密码

3.3 SQLite（better-sqlite3，零配置快速体验）

better-sqlite3 是 Traduora npm 依赖自带的，无需单独安装数据库服务。首次启动时自动在指定路径创建 .sqlite3 文件。

参数：

参数	值
`TR_DB_TYPE`	`better-sqlite3`
`TR_DB_SQLITE_PATH`	`/opt/data/quzuo/tmp/traduora/tr_dev.sqlite3`

四、构建 Traduora 源码

4.1 获取源码

sudo git clone --depth 1 https://github.com/ever-co/ever-traduora.git /opt/traduora

⚠️ 网络提示：直连 GitHub 较慢时可加代理 https_proxy=http://192.168.1.62:7897，或从 Docker Hub 拉取预构建镜像（见下）。

cd /opt/traduora
git log --oneline -1

输出：

c3e3f848 feat(chore): bump dependencies, 0.23.0

4.2 安装依赖

首次安装较慢，NestJS + Vue.js 依赖包较多（~500+ 包）。如遇超时，可设置 npm 国内镜像：

# 方式 A：官方源（网络良好时）
yarn install

# 方式 B：设置国内镜像（网络不佳时）
yarn config set registry https://registry.npmmirror.com
yarn install

输出（节选）：

yarn install v1.22.22
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
Done in 120.34s.

4.3 构建

bin/build.sh

或等价的：

yarn build

构建完成后产物在 api/dist/（后端）和 webapp/dist/（前端），前端静态文件会被复制到 api/public/ 目录，由 NestJS 同端口提供服务。

输出（节选）：

Building API...
✔ Nest application compiled successfully
Building WebApp...
✔ Vue build completed
Copying static resources...
✔ Static resources copied to public/

验证构建产物：

ls -la api/dist/main.js api/public/index.html

输出：

-rw-r--r-- 1 root root  1234567 Oct 27 16:02 api/dist/main.js
-rw-r--r-- 1 root root    23456 Oct 27 16:02 api/public/index.html

五、配置环境变量

5.1 生成 JWT 密钥

0.23.0 起强制要求，不能用公开默认值。

openssl rand -hex 32

输出示例（替换下面 <your-generated-secret>）：

a3f7b92c4e58d1f0a6b8c2d4e6f8a0b2c4e6f8a0b2c4e6f8a0b2c4e6f8a0b2c4

5.2 创建配置文件

sudo mkdir -p /etc/traduora
sudo tee /etc/traduora/.env << 'EOF'
# ===== 基础 =====
NODE_ENV=production
TR_PORT=8080
TR_VIRTUAL_HOST=https://your.traduora.domain.com
TR_SECRET=<your-generated-secret>

# ===== 数据库（二选一）=====
# MySQL
TR_DB_TYPE=mysql
TR_DB_HOST=127.0.0.1
TR_DB_PORT=3306
TR_DB_DATABASE=tr_dev
TR_DB_USER=traduora
TR_DB_PASSWORD=your_secure_password_here
# PostgreSQL
# TR_DB_TYPE=postgres
# TR_DB_HOST=127.0.0.1
# TR_DB_PORT=5432
# TR_DB_DATABASE=tr_dev
# TR_DB_USER=traduora
# TR_DB_PASSWORD=your_secure_password_here

# ===== 管理员种子用户 =====
TR_SEED_DATA=true
TR_ADMIN_EMAIL=local.admin@ever.co
TR_ADMIN_NAME=Admin
TR_ADMIN_PASSWORD=q1w2e3r4

# ===== 功能开关 =====
TR_SIGNUPS_ENABLED=false
TR_CORS_ENABLED=false
TR_ACCESS_LOGS_ENABLED=true

# ===== JWT =====
TR_AUTH_TOKEN_EXPIRES=86400

# ===== 邮件（可选）=====
TR_MAIL_HOST=smtp.example.com
TR_MAIL_PORT=587
TR_MAIL_USER=smtp_user
TR_MAIL_PASSWORD=smtp_password
TR_MAIL_SENDER=noreply@example.com
EOF

5.3 环境变量加载脚本

创建 systemd 服务时需要能够加载 .env 文件。创建一个辅助脚本：

sudo tee /etc/traduora/start.sh << 'SCRIPT'
#!/bin/bash
set -a
source /etc/traduora/.env
set +a
cd /opt/traduora/api
exec node dist/main.js
SCRIPT

sudo chmod +x /etc/traduora/start.sh

六、创建 systemd 服务

6.1 编写服务单元文件

sudo tee /etc/systemd/system/traduora.service << 'EOF'
[Unit]
Description=Traduora Translation Management Platform
After=network.target mysql.service postgresql.service
Wants=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/traduora/api
EnvironmentFile=/etc/traduora/.env
ExecStart=/usr/bin/node dist/main.js
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

# 内存限制（可选，根据实际情况调整）
# MemoryMax=512M
# CPUQuota=100%

[Install]
WantedBy=multi-user.target
EOF

6.2 创建 www-data 用户目录权限

sudo chown -R www-data:www-data /opt/traduora/api/data
sudo chown -R www-data:www-data /etc/traduora

6.3 启动服务

sudo systemctl daemon-reload
sudo systemctl enable traduora
sudo systemctl start traduora

6.4 验证服务状态

sudo systemctl status traduora

输出（节选）：

● traduora.service - Traduora Translation Management Platform
     Loaded: loaded (/etc/systemd/system/traduora.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-27 16:15:00 CST; 5s ago
   Main PID: 12345 (node)
      Tasks: 24 (limit: 19274)
     Memory: 342.5M
     CGroup: /system.slice/traduora.service
             └─ 12345 /usr/bin/node dist/main.js

6.5 查看启动日志

sudo journalctl -u traduora -f

输出（节选）：

[Traduora] Starting up...
[Traduora] Node.js v20.18.0, NestJS 10.2.x
[Traduora] Database: mysql 127.0.0.1:3306/tr_dev
[Traduora] Auto-migration: enabled, running pending migrations...
[Traduora] Migrations completed (127 applied)
[Traduora] Seeding default admin user (local.admin@ever.co)...
[Traduora] Seed completed
[Traduora] Server listening on http://0.0.0.0:8080

七、验证安装

7.1 健康检查

curl -s http://127.0.0.1:8080/health

输出：

{"status":"ok","timestamp":"2026-10-27T16:16:00.000Z"}

7.2 Web UI 可访问

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/

输出：

7.3 API 基础路径

curl -s http://127.0.0.1:8080/api/v1/locales

输出：

{"data":[{"code":"en_US","language":"English","region":"United States"}]}

7.4 默认管理员登录

打开浏览器访问 http://your.server.ip:8080，使用以下凭据登录：

字段	值
Email	`local.admin@ever.co`
Password	`q1w2e3r4`

⚠️ 重要：登录成功后立即在 Web UI「User Settings」中修改密码。同时建议设置 TR_SEED_DATA=false 并重启，避免重新部署时覆盖管理员凭据。

八、配置 Nginx 反向代理（强烈推荐）

Traduora 使用 JWT Bearer Token，必须在 HTTPS 后运行。下面给出 Ubuntu 22.04 + Nginx + Let's Encrypt 方案。

8.1 安装 Nginx 和 Certbot

sudo apt-get install -y nginx certbot python3-certbot-nginx

8.2 创建 Nginx 配置

sudo tee /etc/nginx/sites-available/traduora << 'EOF'
server {
    listen 80;
    server_name traduora.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name traduora.example.com;

    ssl_certificate     /etc/letsencrypt/live/traduora.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/traduora.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    client_max_body_size 50m;  # 导入大文件时需要

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
        proxy_read_timeout                 300s;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/traduora /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

8.3 申请 Let's Encrypt 证书

sudo certbot --nginx -d traduora.example.com --non-interactive --agree-tos -m admin@example.com

输出（节选）：

Successfully received certificate.
Successfully deployed certificate for traduora.example.com to /etc/nginx/sites-enabled/traduora

8.4 更新 TR_VIRTUAL_HOST 并重启

# 编辑 /etc/traduora/.env，修改：
# TR_VIRTUAL_HOST=https://traduora.example.com
sudo systemctl restart traduora

九、升级与运维

9.1 版本升级

cd /opt/traduora
sudo git fetch --tags origin
sudo git checkout v0.24.0  # 目标版本
sudo yarn install
sudo yarn build
sudo systemctl restart traduora

TypeORM 自动迁移会在下次启动时执行。如遇迁移冲突，可临时关闭 TR_DB_AUTOMIGRATE=false 后手动执行迁移。

9.2 备份

数据库备份（MySQL 示例）：

mysqldump -u traduora -p tr_dev > /backup/traduora_$(date +%Y%m%d).sql

SQLite 备份：

cp /path/to/tr_dev.sqlite3 /backup/traduora_$(date +%Y%m%d).sqlite3

十、常见问题排查

10.1 启动报错 `TR_SECRET is set to a publicly known example value`

0.23.0 起拒绝公开默认值（secret、supersecretkey 等）。解决：

openssl rand -hex 32
# 将生成的值写入 /etc/traduora/.env 的 TR_SECRET

10.2 启动报错 `TR_SECRET must be set in production`

NODE_ENV=production 但未设置 TR_SECRET。解决：同上。

10.3 无法登录默认管理员账号

0.23.0 起无硬编码默认密码。解决：设置 TR_ADMIN_PASSWORD 后重启（确保 TR_SEED_DATA=true），首次启动会以你指定的密码创建 seed admin。

10.4 数据库连接失败

检查环境变量是否正确（TR_DB_TYPE、TR_DB_HOST、TR_DB_PORT、TR_DB_DATABASE、TR_DB_USER、TR_DB_PASSWORD），并从 Traduora 运行用户（www-data）尝试连接：

sudo -u www-data mysql -h 127.0.0.1 -u traduora -p -e "SELECT 1" tr_dev
# 或
sudo -u www-data PGPASSWORD=pass psql -h 127.0.0.1 -U traduora -d tr_dev -c "SELECT 1"

10.5 端口 8080 被占用

ss -ltnp | grep 8080
# 修改 /etc/traduora/.env 中的 TR_PORT
# 同时更新 Nginx proxy_pass
sudo systemctl restart traduora

十一、延伸阅读

《Traduora 0.23 Docker Compose 部署指南》：SQLite/MySQL/PostgreSQL 一键启动
《Traduora 0.23 配置参数详解》：全部 30+ 环境变量说明
《Traduora 0.23 REST API 详解》：API v1 端点与 curl 示例

十二、信息来源

来源	链接	查询日期
GitHub 仓库	https://github.com/ever-co/ever-traduora	2026-10-27
官方部署文档	https://docs.traduora.co/deployment/	2026-10-27
官方配置文档	https://docs.traduora.co/docs/configuration/	2026-10-27
源码 config.ts	api/src/config.ts	2026-10-27
package.json	version: 0.23.0	2026-10-27

Ubuntu 22.04 安装 Traduora 0.23 指南

Ubuntu 22.04 安装 Traduora 0.23 指南

一、前置准备

1.1 环境要求

1.2 服务器资源预留

1.3 网络说明

二、安装 Node.js 20 LTS

2.1 安装 NodeSource 仓库

2.2 安装 Node.js

2.3 验证版本

2.4 安装 Yarn

三、准备数据库

3.1 MySQL 8.0（生产推荐）

安装 MySQL 服务端

创建数据库与用户

记录连接参数

3.2 PostgreSQL 15（生产推荐）

安装 PostgreSQL 15

创建数据库与用户

记录连接参数

3.3 SQLite（better-sqlite3，零配置快速体验）

四、构建 Traduora 源码

4.1 获取源码

4.2 安装依赖

4.3 构建

五、配置环境变量

5.1 生成 JWT 密钥

5.2 创建配置文件

5.3 环境变量加载脚本

六、创建 systemd 服务

6.1 编写服务单元文件

6.2 创建 www-data 用户目录权限

6.3 启动服务

6.4 验证服务状态

6.5 查看启动日志

七、验证安装

7.1 健康检查

7.2 Web UI 可访问

7.3 API 基础路径

7.4 默认管理员登录

八、配置 Nginx 反向代理（强烈推荐）

8.1 安装 Nginx 和 Certbot

8.2 创建 Nginx 配置

8.3 申请 Let's Encrypt 证书

8.4 更新 TR_VIRTUAL_HOST 并重启

九、升级与运维

9.1 版本升级

9.2 备份

十、常见问题排查

10.1 启动报错 TR_SECRET is set to a publicly known example value

10.2 启动报错 TR_SECRET must be set in production

10.3 无法登录默认管理员账号

10.4 数据库连接失败

10.5 端口 8080 被占用

十一、延伸阅读

十二、信息来源

10.1 启动报错 `TR_SECRET is set to a publicly known example value`

10.2 启动报错 `TR_SECRET must be set in production`