部署指南

HealthGuard 支持两种部署方式：

• Docker Compose 部署（推荐）：一条命令启动 PostgreSQL、Collector 和 Dashboard。
• 源码运行：适合本地二次开发或调试。

前提条件

• Docker 与 Docker Compose
• （源码方式）Node.js >= 20 与 Yarn 1.22+

方式一：Docker Compose 部署（推荐）

git clone https://github.com/Claud-Lu/healthguard.git
cd healthguard
docker compose up -d

启动后打开浏览器访问 http://localhost，注册账号即可使用。

默认服务端口：

服务	端口	说明
Dashboard	80	可视化后台
Collector	3100	事件采集 API，健康检查 /health
PostgreSQL	5432	数据持久化

自定义环境变量

可通过 .env 文件或 docker compose 环境变量覆盖默认值，常用项包括：

变量	说明	建议
DATABASE_URL	PostgreSQL 连接串	生产环境使用强密码
CORS_ORIGIN	允许的跨域来源	生产环境设置为实际域名，不要保留 *
HEALTHGUARD_AGENT_TOKEN	Repair Agent 认证 Token	生成强随机字符串并妥善保管
JWT_SECRET	会话签名密钥	生产环境必须修改

生产环境注意事项

1. 修改默认数据库密码：docker-compose.yml 中默认密码为 healthguard，生产部署前务必修改。
2. 启用 HTTPS：建议使用反向代理（Nginx / Traefik / Caddy）并配置 TLS 证书。
3. 限制 CORS：将 CORS_ORIGIN 从 * 改为你的 Dashboard 域名。
4. 定期备份 PostgreSQL：使用 pg_dump 或卷快照策略。

方式二：源码运行

git clone https://github.com/Claud-Lu/healthguard.git
cd healthguard
yarn install

# 启动 PostgreSQL（如本地已有可跳过）
docker run -d \
  -e POSTGRES_USER=healthguard \
  -e POSTGRES_PASSWORD=healthguard \
  -e POSTGRES_DB=healthguard \
  -p 5432:5432 \
  postgres:16

# 启动所有服务（Collector + Dashboard + Demo）
yarn dev:local

本地访问地址：

服务	地址
Dashboard	http://127.0.0.1:5175
Collector	http://127.0.0.1:3100/health
Demo	http://127.0.0.1:5174

升级

cd healthguard
git pull
docker compose down
docker compose up -d --build

验证部署

1. 打开 Dashboard 并注册账号。
2. 创建一个 H5 或小程序项目，复制 appKey。
3. 在示例应用中接入 SDK 并触发一个错误。
4. 返回 Dashboard 查看 Issue 列表，确认事件已被聚合。