TransBridge 部署指南

April 23, 2025 · View on GitHub

本文档提供了 TransBridge 的多种部署方式，包括直接运行、Docker 容器、系统服务等。

环境要求

支持的操作系统：Linux, macOS, Windows
内存建议：至少 512MB
硬盘空间：至少 100MB
如需 Redis 缓存：Redis 服务器

直接运行

下载最新的二进制文件或从源码编译：

# 从源码编译
git clone https://github.com/fruitbars/transbridge.git
cd transbridge
./build.sh

# 或直接下载编译好的二进制文件

创建配置文件 config.yml：

server:
  port: 8080

providers:
  - provider: "openai"
    api_url: "https://api.openai.com/v1/chat/completions"
    api_key: "your-api-key"
    timeout: 30
    is_default: true
    models:
      - name: "gpt-3.5-turbo"
        weight: 10
        max_tokens: 2000
        temperature: 0.3

cache:
  enabled: true
  types: ["memory"]
  memory:
    ttl:
      value: "1h"
    max_size: 10000

transapi:
  tokens:
    - "your-api-key"

运行服务：

./transbridge -config config.yml

系统服务部署

Linux (systemd)

创建服务文件：

sudo vim /etc/systemd/system/transbridge.service

添加以下内容：

[Unit]
Description=TransBridge Translation Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/transbridge
ExecStart=/opt/transbridge/transbridge -config /opt/transbridge/config.yml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo mkdir -p /opt/transbridge
sudo cp transbridge /opt/transbridge/
sudo cp config.yml /opt/transbridge/

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable transbridge
sudo systemctl start transbridge

检查状态：

sudo systemctl status transbridge

或使用提供的安装脚本

chmod +x install-transbridge.sh
sudo ./install-transbridge.sh

🐳 Docker 部署

使用 Docker Compose（推荐）

项目提供了完整的 Docker Compose 配置，可以快速部署 TransBridge 服务和 Redis 缓存：

确保已安装 Docker 和 Docker Compose
创建 .env 文件（或使用项目提供的示例）

cp .env.example .env
# 根据需要修改 .env 文件中的配置

启动服务

docker-compose up -d

查看日志

docker-compose logs -f

停止服务

docker-compose down

Docker Compose 配置提供了以下功能：

自动构建和启动 TransBridge 服务
可选的 Redis 缓存服务
配置文件和日志目录挂载
健康检查和自动重启
灵活的环境变量配置

使用 Docker 构建和运行

也可以直接使用 Docker 命令构建和运行：

# 构建镜像
docker build -t transbridge .

# 运行容器
docker run -d -p 8080:8080 -v $(pwd)/config.yml:/app/config.yml --name transbridge transbridge

# 指定版本信息构建
docker build \
  --build-arg BUILD_VERSION=1.0.0 \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%d_%H:%M:%S') \
  --build-arg COMMIT_HASH=$(git rev-parse --short HEAD) \
  -t transbridge:1.0.0 .

Kubernetes 部署

创建配置文件 transbridge-config.yaml：

apiVersion: v1
kind: ConfigMap
metadata:
  name: transbridge-config
data:
  config.yml: |
    server:
      port: 8080
    providers:
      - provider: "openai"
        api_url: "https://api.openai.com/v1/chat/completions"
        api_key: "${OPENAI_API_KEY}"
        timeout: 30
        is_default: true
        models:
          - name: "gpt-3.5-turbo"
            weight: 10
            max_tokens: 2000
            temperature: 0.3
    cache:
      enabled: true
      types: ["memory"]
      memory:
        ttl:
          value: "1h"
        max_size: 10000
    auth:
      tokens:
        - "${AUTH_TOKEN}"

创建部署文件 transbridge-deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: transbridge
  labels:
    app: transbridge
spec:
  replicas: 2
  selector:
    matchLabels:
      app: transbridge
  template:
    metadata:
      labels:
        app: transbridge
    spec:
      containers:
      - name: transbridge
        image: transbridge:latest
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: config-volume
          mountPath: /app/config.yml
          subPath: config.yml
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: transbridge-secrets
              key: openai-api-key
        - name: AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: transbridge-secrets
              key: auth-token
      volumes:
      - name: config-volume
        configMap:
          name: transbridge-config

创建服务文件 transbridge-service.yaml：

apiVersion: v1
kind: Service
metadata:
  name: transbridge
spec:
  selector:
    app: transbridge
  ports:
  - port: 80
    targetPort: 8080
  type: ClusterIP

创建密钥：

kubectl create secret generic transbridge-secrets \
  --from-literal=openai-api-key=your-api-key \
  --from-literal=auth-token=your-auth-token

应用配置：

kubectl apply -f transbridge-config.yaml
kubectl apply -f transbridge-deployment.yaml
kubectl apply -f transbridge-service.yaml

反向代理配置

Nginx

server {
    listen 80;
    server_name translate.yourdomain.com;

    location / {
        proxy_pass http://localhost:8080;
        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;
    }
}

使用 HTTPS：

server {
    listen 443 ssl;
    server_name translate.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        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;
    }
}

性能优化

使用 Redis 缓存提高性能：

cache:
  enabled: true
  types: ["memory", "redis"]
  memory:
    ttl:
      value: "1h"
    max_size: 10000
  redis:
    host: "redis-server"
    port: 6379
    password: "your-password"
    db: 0
    ttl:
      value: "7d"

适当增加 API 提供商的并发限制（如果支持）
调整日志级别以减少 I/O 操作

监控设置

使用 Prometheus 和 Grafana 监控 TransBridge 的运行状态：

启用 Prometheus 指标端点（在配置文件中添加）：

metrics:
  enabled: true
  endpoint: "/metrics"

配置 Prometheus 抓取指标：

scrape_configs:
  - job_name: 'transbridge'
    scrape_interval: 15s
    static_configs:
      - targets: ['transbridge-host:8080']

安全建议

为确保 TransBridge 的安全部署，请考虑以下建议：

API 密钥管理
- 定期轮换 API 密钥
- 对密钥使用访问控制和权限管理
- 避免在代码库或公共场所泄露密钥
网络安全
- 始终使用 HTTPS 保护传输层
- 考虑使用 WAF (Web Application Firewall) 防护
- 限制仅必要的 IP 地址访问 API 服务
日志和审计
- 定期查看日志文件寻找异常模式
- 设置日志轮转和保留策略，避免日志占用过多磁盘空间
- 考虑将日志发送到集中式日志管理系统
容错和恢复
- 设置自动重启服务
- 实施监控和报警系统
- 定期备份配置文件
资源限制
- 设置服务的 CPU 和内存限制
- 配置速率限制，防止 API 滥用
- 考虑设置连接数限制

高可用部署

对于需要高可用性的生产环境，推荐以下部署架构：

                     ┌───────────────┐
                     │  Load Balancer│
                     └───────┬───────┘
                             │
         ┌───────────────────┴───────────────────┐
         │                                       │
┌────────▼─────────┐                 ┌───────────▼────────┐
│ TransBridge Node 1│                 │ TransBridge Node 2 │
└────────┬─────────┘                 └───────────┬────────┘
         │                                       │
         └───────────────────┬───────────────────┘
                             │
                     ┌───────▼───────┐
                     │ Redis Cluster │
                     └───────────────┘

部署步骤：

设置共享的 Redis 缓存集群
部署多个 TransBridge 实例
配置负载均衡器，如 Nginx, HAProxy 或云服务提供商的负载均衡服务
确保所有实例使用相同的配置（除了端口等实例特定配置）

故障排除

日志分析

查看日志以排查问题：

# 查看服务日志
journalctl -u transbridge

# 查看应用日志
tail -f /path/to/translation.log

常见问题

服务无法启动
- 检查配置文件语法
- 确认端口未被占用
- 检查权限问题
翻译失败
- 检查 API 密钥是否有效
- 确认网络连接到翻译服务提供商
- 检查请求格式是否正确
缓存不工作
- 检查缓存配置
- 确认 Redis 服务可用（如使用 Redis）
- 检查内存使用情况
性能问题
- 检查 API 提供商的速率限制
- 考虑增加缓存配置
- 检查系统资源利用率

更新和迁移

版本更新

备份当前配置
```
cp config.yml config.yml.backup
```
停止当前服务
```
sudo systemctl stop transbridge
```

替换可执行文件

cp new-transbridge /opt/transbridge/transbridge

更新配置（如需要）

cp new-config.yml /opt/transbridge/config.yml

启动服务
```
sudo systemctl start transbridge
```

数据迁移

如需将服务迁移到新服务器：

在新服务器上安装 TransBridge
复制配置文件
如果使用 Redis 缓存，可以考虑迁移 Redis 数据（如有必要）
更新 DNS 记录或负载均衡器配置
验证新服务正常工作后，停止旧服务

专业支持

如果您在部署过程中遇到问题，可以：

查阅项目问题跟踪器
加入社区讨论
贡献代码或文档改进

进阶使用场景

与现有系统集成

TransBridge 可以轻松集成到现有系统中，例如：

作为微服务架构的一部分
为内容管理系统提供翻译能力
为聊天机器人或客服系统提供多语言支持

定制开发

TransBridge 设计为易于扩展，如需添加新功能：

添加新的翻译提供商
实现自定义的缓存策略
添加更多的 API 端点

请参考 CONTRIBUTING.md 了解如何贡献代码。

目录