ContextQMD
Back to Daily Stock Analysis

Zeabur 部署指南

docs/docker/zeabur-deployment.md

3.15.010.1 KB
Original Source

Zeabur 部署指南

本指南详细介绍如何在 Zeabur 上部署 A股自选股智能分析系统，包括 WebUI 和 Discord 机器人功能。

目录

1. 部署前准备

1.1 必要条件

  • Zeabur 账号
  • GitHub 账号（用于连接仓库）
  • Discord 开发者账号（如需部署机器人）
  • 相关 API 密钥（如 Gemini API Key、搜索服务 API Key 等）

1.2 仓库准备

确保你的仓库包含以下文件：

  • .github/workflows/docker-publish.yml（已自动创建）
  • docker/Dockerfile（已存在）
  • 完整的项目代码

2. 在 Zeabur 上部署

2.1 连接 GitHub 仓库

  1. 登录 Zeabur 控制台
  2. 点击「新建项目」
  3. 选择「从 GitHub 导入」
  4. 选择你的仓库和分支（推荐使用 main ）
  5. 点击「导入」

2.2 配置构建规则

Zeabur 会自动检测 .github/workflows/docker-publish.yml 文件，并使用 GitHub Actions 构建镜像。

如果没有自动检测到，可以手动配置：

  1. 在项目页面，点击「构建规则」
  2. 选择「Dockerfile」
  3. Dockerfile 路径填写：docker/Dockerfile
  4. 点击「保存」

2.3 启动服务

  1. 等待镜像构建完成
  2. 点击「启动服务」
  3. 服务启动后，你可以在「访问」标签页获取访问地址

2.4 前端构建与静态资源

FastAPI 会自动托管 static/ 目录下的前端资源。前端打包输出位置由 apps/dsa-web/vite.config.ts 决定，默认输出到项目根目录 static/。

Dockerfile 已采用多阶段构建，前端会在镜像构建时自动打包。 如需覆盖默认静态资源，可在宿主机手动构建并挂载到容器内 /app/static。

3. 配置启动命令

3.1 支持的启动模式

系统支持多种启动模式，你可以根据需要配置不同的启动命令：

模式启动命令描述
定时任务模式（默认）python main.py --schedule按计划执行股票分析
FastAPI 模式python main.py --serve启动 FastAPI 并执行分析
仅 FastAPI 模式python main.py --serve-only仅启动 FastAPI，不执行分析
仅大盘复盘python main.py --market-review仅执行大盘复盘分析

3.2 配置启动命令

  1. 在 Zeabur 控制台，进入服务页面
  2. 点击「设置」
  3. 找到「启动命令」配置项
  4. 输入你需要的启动命令，例如：
    • 启动 FastAPI：python main.py --serve
    • 仅启动 FastAPI：python main.py --serve-only --host 0.0.0.0 --port 8000
    • 启动定时任务：python main.py --schedule
  5. 点击「保存」
  6. 重启服务

4. Discord 机器人部署

4.1 准备工作

  1. 创建 Discord 应用和机器人

    • 访问 Discord 开发者平台
    • 点击「New Application」创建新应用
    • 在「Bot」标签页，点击「Add Bot」创建机器人
    • 复制机器人 Token

  2. 配置机器人权限

    • 在「Bot」标签页，向下滚动到「Privileged Gateway Intents」
    • 启用「Server Members Intent」和「Message Content Intent」
    • 在「OAuth2」→「URL Generator」中，选择「bot」范围
    • 选择所需权限（如「Send Messages」、「Read Messages/View Channels」等）
    • 复制生成的邀请链接，将机器人添加到你的服务器

4.2 配置环境变量

在 Zeabur 控制台的「环境变量」配置中，添加以下变量：

变量名说明示例值
DISCORD_BOT_TOKENDiscord 机器人 TokenMTAxMjM0NTY3ODkwMTEyMzQ1Ng.GhIjKl.MnOpQrStUvWxYz1234567890
DISCORD_MAIN_CHANNEL_ID主频道 ID123456789012345678
DISCORD_WEBHOOK_URLDiscord Webhook URL（可选）https://discord.com/api/webhooks/...

4.3 启动机器人

机器人功能默认通过配置启用，无需特殊启动命令。确保你的配置文件中包含机器人相关配置，或通过环境变量设置。

5. 环境变量配置

5.1 基本环境变量

变量名说明默认值
PYTHONUNBUFFERED启用 Python 无缓冲输出1
LOG_DIR日志目录/app/logs
DATABASE_PATH数据库路径/app/data/stock_analysis.db

5.2 API 服务配置

变量名说明默认值
API_HOSTAPI 服务监听地址0.0.0.0
API_PORTAPI 服务端口8000

旧版 WEBUI_HOST/WEBUI_PORT/WEBUI_ENABLED 环境变量仍兼容，会自动转发到 API 服务。

5.3 分析相关配置

变量名说明
ANSPIRE_API_KEYSAnspire Open API 密钥（大模型与搜索共用，推荐）
AIHUBMIX_KEYAIHubMix API 密钥（一 Key 多模型，推荐）
GEMINI_API_KEYGemini API 密钥
OPENAI_API_KEYOpenAI 兼容 API 密钥
SERPAPI_API_KEYSSerpAPI 密钥（推荐）
TAVILY_API_KEYSTavily API 密钥（用逗号分隔）
BOCHA_API_KEYSBocha API 密钥（用逗号分隔）
BRAVE_API_KEYSBrave Search API 密钥（用逗号分隔）
MINIMAX_API_KEYSMiniMax API 密钥（用逗号分隔）
SEARXNG_BASE_URLSSearXNG 实例地址（逗号分隔，无配额兜底，需在 settings.yml 启用 format: json）；留空时默认自动发现公共实例
SEARXNG_PUBLIC_INSTANCES_ENABLED是否在 SEARXNG_BASE_URLS 为空时自动从 searx.space 获取公共实例（默认 true）

5.4 配置方法

在 Zeabur 控制台：

  1. 进入服务页面
  2. 点击「环境变量」
  3. 点击「添加环境变量」
  4. 输入变量名和值
  5. 点击「保存」
  6. 重启服务

6. 挂载配置

6.1 支持的挂载目录

目录说明
/app/data数据库和数据文件
/app/logs日志文件
/app/reports分析报告

6.2 配置挂载

  1. 在 Zeabur 控制台，进入服务页面
  2. 点击「存储」
  3. 点击「添加存储卷」
  4. 选择「持久化存储」
  5. 配置挂载路径：
    • 存储卷路径：/app/data
    • 容器内路径：/app/data
  6. 点击「保存」
  7. 对其他需要挂载的目录重复上述步骤

6.3 注意事项

  • 挂载后，数据会持久化保存，不会因容器重启而丢失
  • 建议至少挂载 /app/data 目录，以保存数据库

7. 健康检查

系统内置了健康检查机制，默认检查：

  • WebUI 模式：检查 http://localhost:8000/health 端点
  • FastAPI 模式：检查 http://localhost:8000/api/health 端点
  • 非服务模式：始终返回健康状态

健康检查配置如下：

dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/api/health || curl -f http://localhost:8000/health \
    || python -c "import sys; sys.exit(0)"

8. 常见问题

8.1 API 服务无法访问

  • 检查启动命令是否包含 --serve 或 --serve-only 参数
  • 检查「访问」标签页是否已配置域名
  • 检查防火墙设置

8.2 机器人不响应

  • 检查 Discord 机器人 Token 是否正确
  • 检查机器人是否已添加到服务器
  • 检查机器人权限是否足够
  • 检查日志文件，查看是否有错误信息

8.3 分析任务不执行

  • 检查定时任务配置是否正确
  • 检查 API 密钥是否有效
  • 检查日志文件，查看是否有错误信息

8.4 数据丢失

  • 确保已挂载 /app/data 目录
  • 检查存储卷配置是否正确

9. 高级配置

9.1 多实例部署

你可以在 Zeabur 上部署多个实例，用于不同的功能：

  1. 一个实例用于 API 服务（python main.py --serve-only）
  2. 一个实例用于定时任务（python main.py --schedule）
  3. 一个实例用于机器人（python main.py --discord-bot）

确保它们共享同一个 /app/data 存储卷，以共享数据库。

9.2 自定义域名

在 Zeabur 控制台的「访问」标签页，你可以：

  1. 使用自动生成的域名
  2. 绑定自定义域名
  3. 配置 HTTPS

10. 更新部署

10.1 自动更新

当你向仓库推送新代码时：

  1. GitHub Actions 会自动构建新镜像
  2. Zeabur 会检测到新镜像
  3. 你可以选择「自动部署」或手动触发部署

10.2 手动更新

  1. 在 Zeabur 控制台，进入服务页面
  2. 点击「部署历史」
  3. 选择「重新部署」
  4. 或点击「更新镜像」

11. 监控和日志

11.1 查看日志

在 Zeabur 控制台，进入服务页面，点击「日志」标签页，可以查看实时日志和历史日志。

11.2 监控指标

Zeabur 提供了基础的监控指标：

  • CPU 使用率
  • 内存使用率
  • 网络流量
  • 磁盘使用率

在「监控」标签页查看详细指标。

12. 故障排查

12.1 查看详细日志

bash
# 进入容器
zeabur exec <服务名> bash

# 查看日志文件
cat /app/logs/stock_analysis_20260125.log

12.2 检查配置

bash
# 进入容器
zeabur exec <服务名> bash

# 检查环境变量
printenv | grep -i discord
printenv | grep -i webui

12.3 测试连接

bash
# 测试网络连接
zeabur exec <服务名> curl -I https://api.discord.com

# 测试 API 连接
zeabur exec <服务名> python -c "import requests; print(requests.get('https://api.discord.com').status_code)"

13. 最佳实践

  1. 使用持久化存储：始终挂载 /app/data 目录，以保存数据库
  2. 配置合理的健康检查：根据实际情况调整健康检查参数
  3. 使用环境变量管理敏感信息：不要将 API 密钥硬编码到代码中
  4. 定期备份数据：定期下载 /app/data 目录的内容进行备份
  5. 使用合适的启动模式：根据需求选择合适的启动命令
  6. 监控服务状态：定期检查服务状态和日志

14. 联系方式

如有问题，欢迎联系项目维护者或在 GitHub Issues 中提问。