Traduora 0.23 配置参数详解

一、概述

Traduora 所有配置均通过环境变量传入，约定统一前缀 TR_（数据库 TypeORM 连接参数除外，也使用 TR_ 前缀）。配置入口在 api/src/config.ts，按功能域可分为：基础运行时、数据库、JWT 认证、管理员种子、导入导出、邮件、OAuth、安全限流、日志调试。

⚠️ 重要：以下参数以 Traduora 0.23.0 源码 api/src/config.ts 为基准整理（2026-10-27 实查）。0.23.0 引入了若干安全变更（强制 TR_SECRET、强制 TR_ADMIN_PASSWORD、拒绝公开默认密钥值），早期版本配置可能不再适用。

二、参数速查表

2.1 基础运行时

环境变量	类型	默认值	必填	说明
`NODE_ENV`	string	`dev`	—	运行时环境，`production` 时强制 TR_SECRET
`TR_PORT`	number	`8080`	—	服务监听端口
`TR_SECRET`	string	无	生产必填	JWT 签名密钥，`openssl rand -hex 32` 生成，拒绝公开默认值
`TR_VIRTUAL_HOST`	string	`http://localhost:8080`	—	外部访问地址，用于邮件链接、OAuth 回调
`TR_PUBLIC_DIR`	string	`./public`	—	前端静态文件目录（NestJS 内置服务）
`TR_TEMPLATES_DIR`	string	`./templates`	—	邮件模板目录

2.2 数据库

环境变量	类型	默认值	说明
`TR_DB_TYPE`	string	`better-sqlite3`	数据库类型，TypeORM 支持的值：`mysql` / `postgres` / `better-sqlite3` / `sqlite` / `mssql`
`TR_DB_HOST`	string	`127.0.0.1`	数据库主机
`TR_DB_PORT`	number	`3306`	数据库端口（MySQL 3306 / PostgreSQL 5432）
`TR_DB_DATABASE`	string	`data/tr_dev.sqlite3`	数据库名（MySQL/PG）或 SQLite 文件路径
`TR_DB_USER`	string	`root`	数据库用户名
`TR_DB_PASSWORD`	string	空字符串	数据库密码
`TR_DB_SQLITE_PATH`	string	`api/data/tr_dev.sqlite3`	SQLite 文件路径（better-sqlite3 专用）
`TR_DB_AUTOMIGRATE`	boolean	`true`	启动时自动执行 pending TypeORM migrations

💡 TypeORM 连接器：源码中固定使用 mysql2 包（connectorPackage: 'mysql2'），mysql 类型强制走 mysql2 驱动。PostgreSQL 和 SQLite 使用默认驱动。

2.3 JWT 与认证

环境变量	类型	默认值	说明
`TR_AUTH_TOKEN_EXPIRES`	number（秒）	`86400`	JWT Access Token 有效期（24 小时）
`TR_SIGNUPS_ENABLED`	boolean	`true`	是否允许用户自注册（生产建议 `false`）

2.4 管理员种子用户（0.23.0 新增/强化）

环境变量	类型	默认值	必填
`TR_SEED_DATA`	boolean	`true`	启动时是否执行 seed 脚本（含管理员创建）
`TR_ADMIN_EMAIL`	string	`local.admin@ever.co`	管理员邮箱
`TR_ADMIN_PASSWORD`	string	空	必填，0.23.0 起无硬编码默认密码
`TR_ADMIN_NAME`	string	`Admin`	管理员显示名称

⚠️ 0.23.0 安全变更：

旧版默认密码 sTr0ngP@ssw0rd!2025 已从源码移除。设置此密码登录会自动失效，需在 Web UI「Forgot password」重置或改 TR_ADMIN_PASSWORD 重启。

TR_ADMIN_PASSWORD 不能为公开已知弱密码（配置里有 hash 黑名单：secret、supersecretkey、mysupersecret、旧 k8s manifest 默认密钥）。

2.5 项目与导入导出

环境变量	类型	默认值	说明
`TR_MAX_PROJECTS_PER_USER`	number	`100`	每用户最多项目数
`TR_DEFAULT_PROJECT_PLAN`	string	`open-source`	新建项目的默认套餐（影响字符串上限）
`TR_IMPORT_MAX_NESTED_LEVELS`	number	`100`	导入嵌套 JSON/YAML 时支持的最大嵌套层数

open-source 套餐默认限制（硬编码，未暴露为环境变量）：

每项目最多 100,000 字符串（term + translation 合计）
可通过自定义套餐覆盖，暂无公开环境变量

2.6 邮件（SMTP）

环境变量	类型	默认值	说明
`TR_MAIL_DEBUG`	boolean	`false`	调试模式：只打印邮件链接不实际发送
`TR_MAIL_SENDER`	string	未设置	发件人（如 `noreply@example.com`）
`TR_MAIL_HOST`	string	未设置	SMTP 主机
`TR_MAIL_PORT`	number	`587`	SMTP 端口
`TR_MAIL_SECURE`	boolean	`false`	是否 TLS（587 端口 STARTTLS 设 false；465 端口 SMTPS 设 true）
`TR_MAIL_REJECT_SELF_SIGNED`	boolean	`true`	是否拒绝自签名证书
`TR_MAIL_USER`	string	未设置	SMTP 认证用户名
`TR_MAIL_PASSWORD`	string	未设置	SMTP 认证密码

2.7 Google OAuth

环境变量	类型	默认值	说明
`TR_AUTH_GOOGLE_ENABLED`	boolean	`false`	启用 Google 登录
`TR_AUTH_GOOGLE_CLIENT_ID`	string	未设置	Google OAuth Client ID
`TR_AUTH_GOOGLE_CLIENT_SECRET`	string	未设置	Google OAuth Client Secret
`TR_AUTH_GOOGLE_REDIRECT_URL`	string	未设置	回调地址，格式 `https://$YOUR_TRADUORA_HOST/auth/callback`

2.8 CORS 与日志

环境变量	类型	默认值	说明
`TR_CORS_ENABLED`	boolean	`false`	启用 CORS（前后端不同域时需要）
`TR_ACCESS_LOGS_ENABLED`	boolean	`true`	打印 HTTP 请求日志到 STDOUT

2.9 安全限流（0.23.0 新增）

环境变量	类型	默认值	说明
`TR_THROTTLE_TTL`	number（毫秒）	`0`	全局限流窗口，0 表示关闭
`TR_THROTTLE_LIMIT`	number	`0`	全局限流时间窗口内最大请求数，0 表示关闭
`TR_AUTH_THROTTLE_TTL`	number（毫秒）	`60000`	认证接口限流窗口（1 分钟）
`TR_AUTH_THROTTLE_LIMIT`	number	生产 `100` / 开发 `10`	认证接口窗口内最大请求数
`TR_LOGIN_ATTEMPTS_TTL`	number（毫秒）	`900000`	登录失败锁定时间（15 分钟）
`TR_LOGIN_ATTEMPTS_MAX`	number	`3`	最大失败尝试次数

2.10 完整参数清单（按源码 config.ts）

以下是源码 api/src/config.ts 中全部配置项，含未在文档中显式说明但存在的：

// 基础
NODE_ENV / env
TR_PORT / port
TR_SECRET / secret  (resolveSecret 有黑名单校验)
TR_VIRTUAL_HOST / virtualHost
TR_PUBLIC_DIR / publicDir
TR_TEMPLATES_DIR / templatesDir
TR_CORS_ENABLED / corsEnabled
TR_ACCESS_LOGS_ENABLED / accessLogsEnabled

// JWT
TR_AUTH_TOKEN_EXPIRES / authTokenExpires

// 项目
TR_SIGNUPS_ENABLED / signupsEnabled
TR_MAX_PROJECTS_PER_USER / maxProjectsPerUser
TR_DEFAULT_PROJECT_PLAN / defaultProjectPlan
TR_DB_AUTOMIGRATE / autoMigrate
TR_SEED_DATA / seedData

// 数据库
TR_DB_TYPE / db.default.type
TR_DB_HOST / db.default.host
TR_DB_PORT / db.default.port
TR_DB_USER / db.default.username
TR_DB_PASSWORD / db.default.password
TR_DB_DATABASE / db.default.database

// 导入
TR_IMPORT_MAX_NESTED_LEVELS / import.maxNestedLevels

// Google OAuth
TR_AUTH_GOOGLE_ENABLED / providers.google.active
TR_AUTH_GOOGLE_CLIENT_SECRET / providers.google.clientSecret
TR_AUTH_GOOGLE_CLIENT_ID / providers.google.clientId
TR_AUTH_GOOGLE_REDIRECT_URL / providers.google.redirectUrl

// 邮件
TR_MAIL_DEBUG / mail.debug
TR_MAIL_SENDER / mail.sender
TR_MAIL_HOST / mail.host
TR_MAIL_PORT / mail.port
TR_MAIL_SECURE / mail.secure
TR_MAIL_REJECT_SELF_SIGNED / mail.rejectSelfSigned
TR_MAIL_USER / mail.auth.user
TR_MAIL_PASSWORD / mail.auth.pass

// 限流（0.23.0）
TR_THROTTLE_TTL / throttle.global.ttl
TR_THROTTLE_LIMIT / throttle.global.limit
TR_AUTH_THROTTLE_TTL / throttle.auth.ttl
TR_AUTH_THROTTLE_LIMIT / throttle.auth.limit
TR_LOGIN_ATTEMPTS_TTL / loginAttempts.ttl
TR_LOGIN_ATTEMPTS_MAX / loginAttempts.maxAttempts

// 管理员种子
TR_ADMIN_EMAIL / defaultAdminCredentialConfig.adminEmail
TR_ADMIN_PASSWORD / defaultAdminCredentialConfig.adminPassword
TR_ADMIN_NAME / defaultAdminCredentialConfig.adminName

三、必填与关键参数详解

3.1 TR_SECRET（JWT 签名密钥）

生产必设，开发环境强烈建议设。用于 JWT Bearer Token 的签名与验证，不设或使用公开已知值会直接启动失败。

生成：

openssl rand -hex 32

输出示例：a3f7b92c4e58d1f0a6b8c2d4e6f8a0b2c4e6f8a0b2c4e6f8a0b2c4e6f8a0b2c4

黑名单（源码中硬编码了以下 SHA-256）：

明文值	说明
`secret`	NestJS 示例默认值
`supersecretkey`	旧版 .env.sample 示例
`mysupersecret`	旧版部署文档示例
旧 k8s preview manifest 密钥	社区公开

如果你的 TR_SECRET 被拒绝：

Error: TR_SECRET is set to a publicly known example value...

解决：生成新值并替换。注意：修改 TR_SECRET 会使所有已有 JWT Token 失效，所有用户和 API 客户端需要重新认证。

3.2 TR_ADMIN_PASSWORD（管理员密码）

0.23.0 起必设，不再有任何硬编码默认值。设置规则：

不能为空字符串或纯空白
不能与黑名单密码相同（与 TR_SECRET 黑名单不同，是独立的一套）
登录成功后可在 Web UI 修改

设置示例：

export TR_ADMIN_PASSWORD='MyStr0ng!P@ss2026'

3.3 TR_DB_TYPE（数据库类型）

值	适用场景	备注
`better-sqlite3`	开发/测试/5 分钟 demo	默认，无需单独 DB 服务
`mysql`	生产推荐	需 MySQL 5.7+，源码固定使用 mysql2 驱动
`postgres`	生产推荐	需 PostgreSQL 12+，官方 compose 用 15-alpine

切换数据库类型只需改 TR_DB_TYPE + 对应的 TR_DB_* 参数，TypeORM 自动迁移会适配。

3.4 TR_DB_AUTOMIGRATE

默认 true。应用启动时自动比较代码中的 migrations 与数据库中已执行的 migrations，执行 pending 部分。升级版本后无需手动跑数据库脚本。

如果升级时遇到迁移冲突，可临时设为 false，手动排查：

-- MySQL/PostgreSQL 查看已执行迁移
SELECT * FROM migrations ORDER BY timestamp DESC LIMIT 5;

3.5 TR_SIGNUPS_ENABLED

生产环境建议设为 false，禁止用户自注册。管理员通过 Project Invite 或手动创建 Project User 来添加成员。

开发环境保留 true 方便测试。

3.6 TR_AUTH_THROTTLE_LIMIT（API 限流）

0.23.0 新增。认证接口（/api/v1/auth/*）限流：

环境	TTL（毫秒）	每窗口最大请求数
production	60000	100
dev	60000	10

开发环境 10 次/分钟较紧（快速测试可能触发），可临时调高：

export TR_AUTH_THROTTLE_LIMIT=60

四、配置示例

4.1 SQLite 快速体验

export NODE_ENV=development
export TR_PORT=8080
export TR_SECRET=$(openssl rand -hex 32)
export TR_ADMIN_PASSWORD=q1w2e3r4
export TR_DB_TYPE=better-sqlite3
export TR_DB_SQLITE_PATH=api/data/tr_dev.sqlite3
export TR_SEED_DATA=true

4.2 MySQL 生产

NODE_ENV=production
TR_PORT=8080
TR_SECRET=<openssl rand -hex 32 输出>
TR_VIRTUAL_HOST=https://traduora.example.com
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=<secure_password>
TR_ADMIN_PASSWORD=<secure_admin_password>
TR_ADMIN_EMAIL=local.admin@ever.co
TR_SEED_DATA=true
TR_SIGNUPS_ENABLED=false
TR_CORS_ENABLED=false
TR_AUTH_TOKEN_EXPIRES=86400
TR_LOGIN_ATTEMPTS_MAX=5
TR_LOGIN_ATTEMPTS_TTL=900000

4.3 PostgreSQL 生产 + Google OAuth + SMTP

NODE_ENV=production
TR_SECRET=<openssl rand -hex 32 输出>
TR_VIRTUAL_HOST=https://traduora.example.com
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=<secure_password>

# 邮件（SMTP TLS STARTTLS）
TR_MAIL_HOST=smtp.gmail.com
TR_MAIL_PORT=587
TR_MAIL_SECURE=false
TR_MAIL_USER=you@gmail.com
TR_MAIL_PASSWORD=<gmail_app_password>
TR_MAIL_SENDER=Traduora<noreply@example.com>

# Google OAuth
TR_AUTH_GOOGLE_ENABLED=true
TR_AUTH_GOOGLE_CLIENT_ID=<google_client_id>
TR_AUTH_GOOGLE_CLIENT_SECRET=<google_client_secret>
TR_AUTH_GOOGLE_REDIRECT_URL=https://traduora.example.com/auth/callback

五、配置注入方式

5.1 Docker Compose（推荐）

environment:
  TR_SECRET: ${TR_SECRET}      # 从 .env 或 shell 变量注入
  TR_PORT: '8080'

5.2 Docker Run

docker run -d \
  -e TR_SECRET=<generated_secret> \
  -e TR_ADMIN_PASSWORD=q1w2e3r4 \
  -p 8080:8080 \
  everco/ever-traduora:latest

5.3 systemd（裸机安装）

EnvironmentFile=/etc/traduora/.env
ExecStart=/usr/bin/node dist/main.js

.env 文件每行一个 KEY=VALUE：

TR_SECRET=a3f7b92c4e58d1f0...
TR_ADMIN_PASSWORD=q1w2e3r4
NODE_ENV=production

5.4 检查运行时生效值

应用启动时，环境变量会被日志打印（脱敏后）：

docker compose logs traduora | grep -i "config\|env\|secret"

或进入容器：

docker exec traduora-app env | grep '^TR_'

六、升级迁移注意

6.1 从 0.22.x 升级到 0.23.0

必做项：

显式设置 TR_SECRET（之前版本可能用了默认值，现在会被拒绝）
显式设置 TR_ADMIN_PASSWORD（旧硬编码密码失效）
TypeORM 自动迁移会执行新增的 throttle/login_attempts 相关表结构变更

升级后检查：

docker compose logs traduora --tail=100 | grep -i "migrat\|secret\|seed\|admin"

输出应包含：

[Traduora] Migrations completed (XXX applied)
[Traduora] Seed completed
[Traduora] Server listening on http://0.0.0.0:8080

6.2 从 SQLite 迁移到 MySQL/PostgreSQL

导出现有 SQLite 数据（Traduora 内部没有直接导出工具，可通过 REST API 拉全量数据）
备份 SQLite 文件
修改 TR_DB_TYPE 和 TR_DB_* 参数
启动，TypeORM 自动在新 DB 中创建表结构
通过 REST API 重新导入之前的数据

七、延伸阅读

《Traduora 介绍与选型指南》：技术栈与架构
《Traduora 0.23 Docker Compose 部署指南》：三种数据库的 compose 模板
《Traduora 0.23 REST API 详解》：API v1 端点与 curl 示例
《Ubuntu 22.04 安装 Traduora 0.23 指南》：裸机 systemd 安装

八、信息来源

来源	路径	查询日期
源码 config.ts	`ever-co/ever-traduora/api/src/config.ts`	2026-10-27
官方配置文档	https://docs.traduora.co/docs/configuration/	2026-10-27
官方 README	https://github.com/ever-co/ever-traduora	2026-10-27
package.json	version: 0.23.0	2026-10-27