Traduora 0.23 Docker Compose 部署指南

一、概述

Ever Co. 官方仓库 ever-co/ever-traduora 提供了三套 docker-compose 方案：

Compose 文件	数据库	适用场景
`docker-compose.demo.yaml`	better-sqlite3（内置）	5 分钟快速体验、原型验证
`docker-compose.yaml`	better-sqlite3	同上，本地自行 build 镜像
`docker-compose.mysql.yaml`	MySQL 5.7	生产推荐，数据持久化
`docker-compose.postgres.yaml`	PostgreSQL 15	生产推荐，数据持久化

本指南覆盖三种实际场景：SQLite 快速启动（验证/测试）、MySQL 生产部署、PostgreSQL 生产部署。

二、前置要求

组件	要求
Docker Engine	≥ 20.10.x
Docker Compose	v2 插件（`docker compose` 子命令）
端口	主机 8080 未被占用（或自行调整）
存储	至少 500 MB 可用空间（镜像 + 数据卷）
网络	能访问 Docker Hub（`docker.io`）

Docker Compose v2 验证：

docker compose version

输出：

Docker Compose version v2.29.1

Docker Engine 验证：

docker version --format '{{.Server.Version}}'

输出：

29.9.2

三、场景一：SQLite 快速启动（5 分钟体验）

3.1 拉取官方仓库

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

⚠️ 网络提示：GitHub 直连受阻时加代理 https_proxy=http://192.168.1.62:7897。

3.2 设置环境变量（关键）

0.23.0 起，必须设置 TR_SECRET 和 TR_ADMIN_PASSWORD，否则启动失败。

export TR_SECRET=$(openssl rand -hex 32)
export TR_ADMIN_PASSWORD=q1w2e3r4
echo "TR_SECRET=$TR_SECRET"

输出示例（实际值以你生成的为准）：

TR_SECRET=a3f7b92c4e58d1f0a6b8c2d4e6f8a0b2c4e6f8a0b2c4e6f8a0b2c4e6f8a0b2c4

3.3 使用官方 demo compose 启动

docker compose -f docker-compose.demo.yaml up -d

输出（节选）：

[+] Running 2/2
 ✔ Network ever-traduora_overlay  Created
 ✔ Container traduora             Started

3.4 验证启动

docker compose -f docker-compose.demo.yaml ps

输出：

NAME      IMAGE                           COMMAND                  SERVICE    CREATED         STATUS         PORTS
traduora  everco/ever-traduora:latest   "./docker-entrypoi..."   traduora   10 seconds ago  Up 9 seconds  0.0.0.0:8080->8080/tcp

健康检查：

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

输出：

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

3.5 登录验证

浏览器访问 http://你的服务器IP:8080：

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

3.6 停止与清理

# 停止
docker compose -f docker-compose.demo.yaml down

# 停止并删除数据卷（⚠️ 会清空 SQLite 数据）
docker compose -f docker-compose.demo.yaml down -v

数据持久化目录：./traduora_sqlite_data/（compose 自动创建的命名卷，可通过 docker volume ls 查看）。

四、场景二：MySQL 生产部署

4.1 目录与环境准备

mkdir -p /opt/traduora/compose-mysql
cd /opt/traduora/compose-mysql

# 生成密钥
export TR_SECRET=$(openssl rand -hex 32)
export TR_ADMIN_PASSWORD=q1w2e3r4

4.2 编写自定义 Compose 文件

以下 compose 是在官方 docker-compose.mysql.yaml 基础上的生产增强版，显式设置项目名、子网、端口映射、健康检查等。

cat > docker-compose.yml << 'YAML'
version: '3.7'

name: traduora-mysql-stack

services:
  traduora:
    image: everco/ever-traduora:latest
    container_name: traduora-app
    ports:
      - '8080:8080'
    environment:
      NODE_ENV: production
      TR_PORT: 8080
      TR_SECRET: ${TR_SECRET}
      TR_VIRTUAL_HOST: https://traduora.example.com
      TR_DB_TYPE: mysql
      TR_DB_HOST: mysqldb
      TR_DB_PORT: 3306
      TR_DB_DATABASE: tr_dev
      TR_DB_USER: traduora
      TR_DB_PASSWORD: change_me
      TR_ADMIN_EMAIL: local.admin@ever.co
      TR_ADMIN_PASSWORD: ${TR_ADMIN_PASSWORD}
      TR_ADMIN_NAME: Admin
      TR_SEED_DATA: 'true'
      TR_SIGNUPS_ENABLED: 'false'
      TR_CORS_ENABLED: 'false'
      TR_DB_AUTOMIGRATE: 'true'
    entrypoint: './docker-entrypoint.compose.sh'
    restart: unless-stopped
    depends_on:
      mysqldb:
        condition: service_healthy
    networks:
      - traduora_net
    healthcheck:
      test: ['CMD', 'curl', '-sf', 'http://localhost:8080/health']
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s

  mysqldb:
    image: mysql:8.0
    container_name: traduora-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root_secure_password
      MYSQL_DATABASE: tr_dev
      MYSQL_USER: traduora
      MYSQL_PASSWORD: change_me
      MYSQL_ALLOW_EMPTY_PASSWORD: 'false'
    volumes:
      - /opt/traduora/compose-mysql/mysql_data:/var/lib/mysql
      - /opt/traduora/compose-mysql/mysql-conf:/etc/mysql/conf.d
    networks:
      - traduora_net
    healthcheck:
      test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-uroot', '-proot_secure_password']
      interval: 10s
      timeout: 5s
      retries: 10

networks:
  traduora_net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.56.0/24
YAML

4.3 启动

docker compose up -d

输出（节选）：

[+] Running 4/4
 ✔ Network traduora-mysql-stack_traduora_net  Created
 ✔ Volume "traduora-mysql-stack_mysql_data"    Created
 ✔ Container traduora-mysql                      Started
 ✔ Container traduora-app                       Started

4.4 等待就绪

MySQL 初始化需要 10-30 秒，等 Traduora 健康检查通过：

docker compose logs -f traduora --tail=30

输出（节选）：

traduora-app  | [Traduora] Waiting for MySQL to be ready...
traduora-app  | [Traduora] MySQL connected
traduora-app  | [Traduora] Running auto-migrations...
traduora-app  | [Traduora] Migrations completed (127 applied)
traduora-app  | [Traduora] Seeding default admin user...
traduora-app  | [Traduora] Server listening on http://0.0.0.0:8080

4.5 验证

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

输出：

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

docker compose ps

输出：

NAME            IMAGE                         STATUS         PORTS
traduora-app    everco/ever-traduora:latest   healthy        0.0.0.0:8080->8080/tcp
traduora-mysql  mysql:8.0                     healthy        3306/tcp

4.6 停止与清理

# 停止保留数据
docker compose down

# 停止 + 删除数据卷（⚠️ 清空 MySQL 数据）
docker compose down -v

# 停止 + 删除匿名卷
docker compose down -v --remove-orphans

五、场景三：PostgreSQL 生产部署

5.1 Compose 文件

cat > docker-compose.yml << 'YAML'
version: '3.7'

name: traduora-pg-stack

services:
  traduora:
    image: everco/ever-traduora:latest
    container_name: traduora-app
    ports:
      - '8080:8080'
    environment:
      NODE_ENV: production
      TR_PORT: 8080
      TR_SECRET: ${TR_SECRET}
      TR_VIRTUAL_HOST: https://traduora.example.com
      TR_DB_TYPE: postgres
      TR_DB_HOST: postgresdb
      TR_DB_PORT: 5432
      TR_DB_DATABASE: tr_dev
      TR_DB_USER: traduora
      TR_DB_PASSWORD: change_me
      TR_ADMIN_EMAIL: local.admin@ever.co
      TR_ADMIN_PASSWORD: ${TR_ADMIN_PASSWORD}
      TR_ADMIN_NAME: Admin
      TR_SEED_DATA: 'true'
      TR_SIGNUPS_ENABLED: 'false'
      TR_DB_AUTOMIGRATE: 'true'
    entrypoint: './docker-entrypoint.compose.sh'
    restart: unless-stopped
    depends_on:
      postgresdb:
        condition: service_healthy
    networks:
      - traduora_net
    healthcheck:
      test: ['CMD', 'curl', '-sf', 'http://localhost:8080/health']
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s

  postgresdb:
    image: postgres:15-alpine
    container_name: traduora-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: tr_dev
      POSTGRES_USER: traduora
      POSTGRES_PASSWORD: change_me
      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
    volumes:
      - /opt/traduora/compose-pg/pg_data:/var/lib/postgresql/data
    networks:
      - traduora_net
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U traduora -d tr_dev']
      interval: 10s
      timeout: 5s
      retries: 10

networks:
  traduora_net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.56.0/24
YAML

5.2 启动

同 MySQL：

docker compose up -d

验证同上。

六、生产环境最佳实践

6.1 必做配置

项	说明
TR_SECRET	`openssl rand -hex 32` 生成，不能是公开默认值
TR_ADMIN_PASSWORD	显式设置，0.23.0 起无硬编码默认值
TR_VIRTUAL_HOST	设为正式域名（`https://traduora.example.com`）
TR_SIGNUPS_ENABLED	生产设为 `false`，防止随意注册
NODE_ENV	`production`
HTTPS 反向代理	官方强烈推荐，JWT Token 不能裸奔 HTTP
restart policy	`unless-stopped`，容器崩溃自动重启

6.2 数据持久化策略

SQLite（demo 模式）：

数据在命名卷 ./traduora_sqlite_data
备份直接 cp 卷内容
不建议生产使用（better-sqlite3 并发写能力有限）

MySQL/PostgreSQL：

用 bind mount（./mysql_data 或 ./pg_data）便于宿主机备份
定期执行 mysqldump / pg_dump 并上传对象存储

6.3 资源限制

compose 中可添加资源限制（可选）：

traduora:
  deploy:
    resources:
      limits:
        cpus: '1.0'
        memory: 512M
      reservations:
        cpus: '0.25'
        memory: 256M

Traduora Node.js 进程常规内存 200-400 MB，可按需调整。

6.4 日志管理

# 查看实时日志
docker compose logs -f traduora

# 查看最近 100 行
docker compose logs --tail=100 traduora

# 只看某个服务
docker compose logs -f mysqldb

6.5 更新与升级

# 拉取最新镜像
docker compose pull

# 滚动重建
docker compose up -d

# 查看版本
docker run --rm everco/ever-traduora:latest cat package.json | grep '"version"'

七、常见问题

7.1 `docker compose up` 启动后立即退出

检查 docker compose logs：

docker compose logs traduora --tail=50

常见原因：

TR_SECRET 为空或使用了公开默认值 → 重新用 openssl rand -hex 32 生成
TR_DB_* 参数错误 → 检查 MySQL/PostgreSQL 是否真的启动完毕（depends_on + condition: service_healthy 是关键）
0.23.0 起 TR_ADMIN_PASSWORD 必须设置

7.2 MySQL/PostgreSQL 连接超时

MySQL 初始化约 15-30 秒，如果 Traduora 过早启动，会重试连接。确保 compose 文件中使用：

depends_on:
  mysqldb:
    condition: service_healthy

7.3 端口冲突

检查：

ss -ltnp | grep 8080

修改 compose 的端口映射：

ports:
  - '8081:8080'  # 主机 8081，容器仍用 8080

7.4 SQLite 数据卷权限问题

首次启动可能因权限报错。修复：

mkdir -p traduora_sqlite_data
chown -R 999:999 traduora_sqlite_data

7.5 从旧版本升级

# 1. 备份数据库
mysqldump ... > backup.sql

# 2. 拉新镜像
docker compose pull

# 3. 重建
docker compose up -d

# 4. TypeORM 自动执行 migrations

八、延伸阅读

《Traduora 介绍与选型指南》：技术栈、版本历史、同类对比
《Ubuntu 22.04 安装 Traduora 0.23 指南》：裸机 systemd 安装
《Traduora 0.23 配置参数详解》：30+ 环境变量逐项说明
《Traduora 0.23 REST API 详解》：API v1 端点与 curl 示例

九、信息来源

来源	链接	查询日期
官方 docker-compose.demo.yaml	GitHub ever-co/ever-traduora	2026-10-27
官方 docker-compose.mysql.yaml	GitHub ever-co/ever-traduora	2026-10-27
官方 docker-compose.postgres.yaml	GitHub ever-co/ever-traduora	2026-10-27
官方部署文档	https://docs.traduora.co/deployment/	2026-10-27
Docker Hub	https://hub.docker.com/r/everco/ever-traduora	2026-10-27

Traduora 0.23 Docker Compose 部署指南

Traduora 0.23 Docker Compose 部署指南

一、概述

二、前置要求

三、场景一：SQLite 快速启动（5 分钟体验）

3.1 拉取官方仓库

3.2 设置环境变量（关键）

3.3 使用官方 demo compose 启动

3.4 验证启动

3.5 登录验证

3.6 停止与清理

四、场景二：MySQL 生产部署

4.1 目录与环境准备

4.2 编写自定义 Compose 文件

4.3 启动

4.4 等待就绪

4.5 验证

4.6 停止与清理

五、场景三：PostgreSQL 生产部署

5.1 Compose 文件

5.2 启动

六、生产环境最佳实践

6.1 必做配置

6.2 数据持久化策略

6.3 资源限制

6.4 日志管理

6.5 更新与升级

七、常见问题

7.1 docker compose up 启动后立即退出

7.2 MySQL/PostgreSQL 连接超时

7.3 端口冲突

7.4 SQLite 数据卷权限问题

7.5 从旧版本升级

八、延伸阅读

九、信息来源

7.1 `docker compose up` 启动后立即退出