Gainium

Gainium Docker Compose 设置

为 Gainium 交易平台提供完整的 Docker 编排，包含所有微服务、数据库和前端应用。

📋 目录

• 前置条件
• 快速开始
• 环境配置
• 服务概览
• Docker 镜像
• 使用命令
• 故障排除
• 高级配置
• 📋 更新日志

🔧 前置条件

开始之前，请确保已安装：

1. Docker（v20.10+）和 Docker Compose（v2.0+）
2. 至少 4GB RAM 和 5GB 可用磁盘空间

⚡ 快速开始

1. 克隆并进入目录

# Clone the repository
git clone https://github.com/Gainium/docker-sh.git

# Navigate into the cloned directory
cd docker-sh

2. 设置环境

# Copy the sample environment file
cp .env.sample .env

# Generate this installation's encryption key (see below — back it up)
./setupEncryptKey.sh

# Edit the .env file with your configuration
nano .env  # or use your preferred editor

3. 配置变量（可选）

编辑 .env 文件，并根据需要配置变量：

# Coinbase API credentials (only required if using Coinbase)
COINBASEKEY=your_coinbase_api_key
COINBASESECRET=your_coinbase_secret

4. 启动所有服务

# Start all services in background
docker-compose up -d

# View logs (optional)
docker-compose logs -f

5. 验证设置

• API：http://localhost:7503（GraphQL 端点）
• WebSocket：ws://localhost:7502（实时数据）
• 前端：http://localhost:7500（Web 控制面板）

🔧 环境配置

🔐 加密密钥（ENCRYPT_KEY）

用户添加的交易所 API 凭据会以加密形式存储，而 ENCRYPT_KEY 用于加密这些凭据。请为你的部署生成一个密钥：

./setupEncryptKey.sh

如果没有设置，应用会回退到编译进镜像的密钥—— 所有可自托管部署都使用同一个密钥，而且该密钥可在 公开源代码中读取——因此，仅凭数据库副本就足以 解密所有已存储的凭据。使用你自己的密钥则不会有这个问题。

请将密钥备份到此主机之外的位置。 如果密钥丢失， 任何人都无法恢复已存储的交易所凭据，所有用户都必须 重新输入密钥。

已经在未设置密钥的情况下运行？你可以现在设置密钥， 之后再重新加密现有数据——期间不会出现故障。请参阅部署指南中的 加密密钥。

可选变量

变量	描述	示例	必需
COINBASEKEY	Coinbase Pro API 密钥	your_api_key	仅在使用 Coinbase 时需要
COINBASESECRET	Coinbase Pro API 密钥密文	your_secret	仅在使用 Coinbase 时需要
PRICE_CONNECTOR_EXCHANGES	以逗号分隔的交易所列表，用于 WebSocket 价格连接器	binance,kucoin,bybit	否（未设置时连接所有交易所）

数据库配置

变量	默认值	描述
MONGO_DB_USERNAME	user	MongoDB 用户名
MONGO_DB_PASSWORD	password	MongoDB 密码
MONGO_DB_NAME	gainium	数据库名称
REDIS_PASSWORD	H2Ga1DB1alBg	Redis 密码
RABBIT_USER	gainium	RabbitMQ 用户名
RABBIT_PASSWORD	bdo3nyVMX5l6	RabbitMQ 密码

服务端口

服务	端口	描述
GRAPH_QL_PORT	7503	主 API GraphQL 端点
WS_PORT	7502	WebSocket 流式服务
PORT	7500	前端 Web 控制面板
BACKTEST_PORT	7515	回测服务

🔒 仅公开仪表板和 API

内部服务不进行任何身份验证。它们之所以安全，是因为无法访问，仅此而已。 如有需要，可公开 PORT（7500）和 GRAPH_QL_PORT（7503）；其他所有服务都应留在内部 Docker 网络中，或绑定到主机的 loopback 接口，并且不要在防火墙中开放这些端口。

其中有两项服务尤其需要注意：

• exchange-connector。 它是一个凭据透传代理，GET /verify / GET /keyPermissions 会接收你提供的任意交易所 API 密钥，向交易平台验证密钥是否有效并返回结果——包括该密钥是否有提现权限。它没有调用方身份验证，也不会限流，这是有意为之，因为唯一预期的调用方是 balancer。如果能从外部访问，它就会变成被盗交易所密钥的批量验证器。切勿公开其端口。
• paper-trading。 POST /user 会使用调用方指定的初始余额创建账户，且不进行身份验证。资金是模拟的，因此损失的是被污染的数据而非金钱，但这并不意味着可以公开此端点。在单主机部署中，你可以为此服务设置 APP_HOST=127.0.0.1，使其完全脱离网络。

如果在整个服务栈前放置反向代理，只允许仪表板和 API 路由通过。此 compose 文件中的其他服务都不适合暴露给你无法控制的网络。

⚠️ 重要：PRICEROLE 配置

PRICEROLE 环境变量用于控制系统处理价格更新的方式，并可能显著影响资源使用：

值	描述	资源使用量	使用场景
all	默认值 - 同时连接行情和 K 线流	高 - 实时行情更新	模拟交易、高频交易
candle	仅连接 K 线流，忽略行情流	低 - 每 2.5 分钟定时更新	不使用模拟交易的实盘交易
ticker	仅连接行情流	中 - 仅实时行情	特定行情监控

⚠️ 资源影响警告：

• PRICEROLE=all 可能因高频行情更新而消耗大量资源
• 如果不使用模拟交易，请设置 PRICEROLE=candle 以降低资源使用量
• 使用 PRICEROLE=candle 时，机器人中与价格相关的方法会每 2.5 分钟定时运行一次，而非实时运行

配置示例：

# For production without paper trading (recommended)
PRICEROLE=candle

# For development/paper trading (default)
PRICEROLE=all

# For ticker monitoring only
PRICEROLE=ticker

🔗 PRICE_CONNECTOR_EXCHANGES 配置

PRICE_CONNECTOR_EXCHANGES 环境变量用于控制 WebSocket 价格连接器连接哪些交易所，以接收价格数据。

支持的交易所：

• binance - Binance 交易所
• binanceus - Binance US 交易所
• kucoin - KuCoin 交易所
• bybit - Bybit 交易所
• okx - OKX 交易所
• bitget - Bitget 交易所
• coinbase - Coinbase 交易所
• kraken - Kraken 交易所
• hyperliquid - Hyperliquid 交易所

配置选项：

# Connect to all exchanges (default behavior)
# Leave variable unset or empty
PRICE_CONNECTOR_EXCHANGES=

# Connect to specific exchanges only
PRICE_CONNECTOR_EXCHANGES=binance,kucoin,bybit

# Connect to a single exchange
PRICE_CONNECTOR_EXCHANGES=binance

# Connect to multiple exchanges
PRICE_CONNECTOR_EXCHANGES=binance,binanceus,coinbase,okx

重要说明：

• 如果未设置 PRICE_CONNECTOR_EXCHANGES 或其值为空，连接器将连接到所有支持的交易所
• 使用逗号分隔各值，交易所名称之间不要加空格
• 无效的交易所名称将被忽略
• 此设置仅影响 WebSocket 价格连接器服务

前端运行时配置

前端服务现已支持用于服务器和 WebSocket 配置的运行时环境变量：

# Default values (for local development)
NEXT_PUBLIC_SERVER=http://localhost:7503
NEXT_PUBLIC_WS=ws://localhost:7502

# For remote deployment, set these to your domain/IP
NEXT_PUBLIC_SERVER=https://api.yourdomain.com
NEXT_PUBLIC_WS=wss://ws.yourdomain.com

重要说明：

• 这些变量在容器运行时设置，而非构建时
• 默认值适用于本地开发
• 生产环境部署时，请更新这些值以匹配你的服务器
• 更改环境变量后，必须重新创建容器

使用示例：

# Local development (uses defaults)
docker-compose up -d

# Production deployment - update docker-compose.yml:
# services:
#   frontend:
#     environment:
#       - NEXT_PUBLIC_SERVER=https://api.mycompany.com
#       - NEXT_PUBLIC_WS=wss://ws.mycompany.com

🏗️ 服务概览

基础设施服务（3 项）

• mongo：带持久化存储的 MongoDB 数据库
• redis：Redis 缓存和会话存储
• rabbit：RabbitMQ 消息代理

连接器服务（4 个）

• exchange-connector：交易所 API 集成
• paper-trading：模拟交易
• user-update-connector：实时用户更新
• price-connector：价格数据流

主应用服务（10 个）

所有服务共享同一套代码库，但运行不同的命令：

• api：GraphQL API 服务端（端口 7503）
• stream：WebSocket 流式传输（端口 7502）
• bots-dca：DCA 交易机器人
• bots-grid：网格交易机器人
• bots-combo：组合交易机器人
• bots-hedge-combo：对冲组合机器人
• bots-hedge-dca：对冲 DCA 机器人
• indicators：技术指标处理器
• cron：计划任务和维护
• backtest：策略回测服务

前端服务（1 个）

• frontend：Next.js Web 控制面板（端口 7500）

总计：18 个服务

🐳 Docker 镜像

以下镜像来自镜像仓库：

镜像	版本	使用该镜像的服务
docker.gainium.io/gainium/exchange-connector	1.0.0	exchange-connector
docker.gainium.io/gainium/paper-trading	1.0.0	paper-trading
docker.gainium.io/gainium/websocket-connector	1.0.0	user-update-connector, price-connector
docker.gainium.io/gainium/main-app	1.0.0	所有 10 个 main-app 服务
docker.gainium.io/gainium/frontend	1.0.0	frontend

外部镜像：

• bitnami/mongodb:latest
• bitnami/redis:latest
• bitnami/rabbitmq:latest

🚀 使用命令

启动服务

# Start all services
docker-compose up -d

# Start specific services
docker-compose up -d mongo redis rabbit
docker-compose up -d api frontend

# Start with build (rebuild images)
docker-compose up -d --build

# Start and view logs
docker-compose up

更新镜像

先运行 git pull——这是升级流程的一部分，不可省略。 镜像标签是受版本控制的 docker-compose.yml 中的默认值 （${MAIN_APP_VERSION:-…}），新版本通过更新此代码库中的标签发布。如果本地检出版本过旧，运行 docker-compose pull 虽然会成功，但只会重新拉取你当前正在使用的标签，因此不会更新任何内容。也可以使用控制面板的 管理 → 服务 选项卡，该选项卡会在 .versions.env 中固定镜像仓库版本，无需运行 git pull。

# Update and restart services (the full upgrade)
git pull
docker-compose pull && docker-compose up -d

# Pull latest images from registry only
docker-compose pull

# Pull specific image
docker pull docker.gainium.io/gainium/main-app:1.0.0
docker pull docker.gainium.io/gainium/frontend:1.0.0

# See which tags your checkout would actually pull
docker compose config --images

管理服务

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ deletes database data)
docker-compose down -v

# Restart specific service
docker-compose restart api
docker-compose restart frontend

# Scale a service (if supported)
docker-compose up -d --scale bots-dca=2

监控与调试

# View logs for all services
docker-compose logs -f

# View logs for specific service
docker-compose logs -f api
docker-compose logs -f frontend
docker-compose logs -f mongo

# View service status
docker-compose ps

# Execute command in running container
docker-compose exec api bash
docker-compose exec mongo mongosh

# View resource usage
docker stats

维护命令

# Update images (git pull first — see "Updating Images" above)
git pull
docker-compose pull
docker-compose up -d

# Clean up unused resources
docker system prune

# Remove all Gainium images
docker images | grep docker.gainium.io | awk '{print $3}' | xargs docker rmi

# Reset everything (⚠️ deletes all data)
docker-compose down -v --rmi all

重置密码

这是可自托管安装中唯一的密码恢复方式。 没有“忘记密码”邮件链接——该流程仅适用于已配置邮件投递的 Gainium 托管服务。在你自己的部署中，无法登录的用户需要由拥有 Shell 访问权限的操作员运行以下命令。在将账户交给用户之前，请做好相应安排。

要从命令行重置用户密码：

# Using helper script (recommended)
./resetPassword.sh <username> <newPassword>

# Or using Docker Compose directly
docker-compose run --rm cli-runner npm run cli:reset-password -- <username> <newPassword>

**密码要求：**至少 6 个字符，包含大写字母、小写字母和数字。

示例：

./resetPassword.sh admin MyNewPass123

此操作会让用户在所有位置退出登录。 该账户的所有现有会话都会被撤销，因此用户（以及持有其会话的任何其他人）都必须使用新密码重新登录。这是有意为之：如果你是因为账户可能已遭入侵而重置密码，就必须确保入侵者的会话不会在重置后继续有效。

用户需要执行此操作的情况

• 忘记密码，无法登录。 唯一的处理方式——没有邮件链接。
• 忘记密码，但仍处于登录状态。 同样需要使用此方式。自 main-app 1.52.0 起，应用内的 设置 → 更改密码 表单要求提供账户的 当前 密码，因此，仍处于登录状态但已不记得当前密码的用户无法自行更改密码。（在该版本之前，只需会话即可设置新密码，这意味着任何泄露的会话都可能导致账户被完全接管—— GHSA-4m6h-m5mj-733x。）
• 怀疑账户已遭入侵。 请在此处重置，而不是在应用中重置：此命令会撤销所有会话，从而将入侵者踢出账户。

运维说明

• 用户名是账户的电子邮件地址，匹配时不区分大小写。
• 新密码会以 bcrypt 哈希形式写入，与其他所有写入路径相同——绝不会以可逆方式存储。
• 命令运行期间，密码会出现在 shell 历史记录和进程列表中。若在共享主机上操作，请事后清除密码（history -d），并让用户重新登录后更改密码。
• 该命令会针对正在使用的数据库运行 cli-runner；之后无需重启服务栈。

🔍 故障排除

常见问题

1. 服务无法启动 - 未找到镜像

# Error: pull access denied or image not found
# Solution: Check image names and tags in docker-compose.yml
docker-compose pull  # Pull all required images

2. 服务无法启动 - 端口已被占用

# Find what's using the port
lsof -i :7503
# Kill the process or change the port in .env

3. 数据库连接问题

# Check if MongoDB is running
docker-compose logs mongo
# Reset database
docker-compose restart mongo

4. 内存不足错误

# Check available resources
docker stats
# Increase Docker memory limit or reduce running services

5. Mac 兼容性问题（Apple Silicon M1/M2）

问题：服务在 Mac 上无法启动，在 Apple Silicon 芯片上尤为常见

# Common error messages:
# "exec format error"
# "WARNING: The requested image's platform does not match the detected host platform"
# Services keep restarting or fail to start

解决方案：

选项 1：使用 Docker Desktop 的 Rosetta 2 仿真

1. 打开 Docker Desktop
2. 前往 Settings → General
3. 勾选“Use Rosetta for x86/amd64 emulation on Apple Silicon”
4. 重启 Docker Desktop
5. 运行：docker-compose down && docker-compose up -d

选项 2：启用 Docker 实验性功能

# Enable buildx for multi-platform support
docker buildx create --use
docker buildx inspect --bootstrap

# Pull ARM64 specific images
docker pull --platform linux/arm64 bitnami/redis:latest
docker pull --platform linux/arm64 bitnami/rabbitmq:latest

选项 3：检查 Docker Desktop 设置

1. 确保使用的是最新版本的 Docker Desktop
2. 前往 Settings → Resources 并分配足够的资源：
   • 内存：至少 4GB
   • CPU：至少 2 个核心
3. 重启 Docker Desktop

验证：

# Check if all services are running properly
docker-compose ps

# Check logs for any platform-related errors
docker-compose logs | grep -i "platform\|arch\|format"

# Test database connections
docker-compose exec mongo mongosh --version
docker-compose exec redis redis-cli ping

6. Docker Registry 超时问题

问题：拉取镜像时连接 Docker Registry 超时

# Common error message:
# "Error response from daemon: Get "https://docker.gainium.io/v2/gainium/main-app/manifests/sha256:..." context deadline exceeded"

解决方案： 这通常是在从 Docker Registry 拉取镜像时发生的网络超时问题。大多数情况下，重试命令即可解决：

# Retry pulling images
docker-compose pull

# If pull succeeds, restart the services
docker-compose up -d

# Alternative: Pull specific image that failed
docker pull docker.gainium.io/gainium/main-app:1.0.0

注意：Registry 超时通常是暂时的网络问题。如果问题持续存在，请检查互联网连接，或几分钟后重试。

调试步骤

1. 检查服务状态：

   docker-compose ps
   

2. 查看详细日志：

   docker-compose logs serviceName
   

3. 测试连接：

   # Test API
   curl http://localhost:7503/health
   
   # Test WebSocket
   wscat -c ws://localhost:7502
   

4. 检查容器：

   docker-compose exec api bash
   

� 高级配置

特定环境的设置

创建不同的环境文件：

# Development
cp .env.sample .env.development

# Production  
cp .env.sample .env.production

# Use specific environment
docker-compose --env-file .env.production up -d

性能调优

# Limit service resources in docker-compose.yml
services:
  api:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '0.5'

健康检查

添加健康检查以监控服务状态：

# Check all services health
docker-compose ps

📊 监控

服务端点

• API 健康检查：http://localhost:7503/health
• API GraphQL：http://localhost:7503/graphql
• WebSocket：ws://localhost:7502
• 前端：http://localhost:7500
• RabbitMQ 管理界面：http://localhost:15672 (guest/guest)

日志管理

# Rotate logs to prevent disk space issues
docker-compose logs --no-log-prefix api > api.log 2>&1

📝 重要说明

1. 首次运行：首次拉取镜像可能需要 5-10 分钟，具体取决于网速
2. 资源要求：系统资源要求较低（建议至少 4GB RAM）
3. 数据持久化：数据库数据存储在 Docker 卷中
4. 网络：所有服务都通过默认的 Docker bridge 网络通信

🆘 获取帮助

如果遇到问题：

1. 查看本 README 的故障排除部分
2. 查看服务日志：docker-compose logs serviceName
3. 检查 Docker 资源：docker stats
4. 验证环境配置：cat .env

如需进一步帮助，请联系 Gainium 开发团队，并提供：

• .env 文件（请隐藏密钥）
• 显示错误的服务日志
• docker-compose ps 的输出