InsightReply/docs/DEPLOYMENT.md

InsightReply 部署与发布指南

本文档记录了 InsightReply 项目在生产环境下的自动化持续部署 (CI/CD) 策略。 由于项目由后端 (Go) 和前端浏览器扩展 (Vue) 组成，为了保证构建速度并解耦故障，我们采用了前后端分离的部署工作流。

---

🏗 CI/CD 架构方案

我们的自动部署工作流依赖于 Gitea Actions，运行在 main 分支的推送动作上。

1. 后端自动化部署 (Docker)

工作流文件：.gitea/workflows/backend-deploy.yml 触发条件：当推送代码到 main 分支，且 server/** 目录有变更时触发。

执行流程：

1. 获取代码并安装 Go 1.24 环境。
2. 交叉编译：在 Runner 上编译出适用于 Linux ARM64 的可执行文件 server_bin。
3. 准备部署包：将可执行文件、Dockerfile、docker-compose.yml 收集到部署文件夹。
4. Rsync 同步：将文件同步到生产服务器的 /var/admin/InsightReply/server/ 目录下。
5. 平滑重启服务：通过 SSH 远程执行 docker-compose up -d --build，实现不宕机更新。

Warning

Rsync 安全提醒：--delete 参数会删除目标目录中不在源端的文件。务必配合 --exclude 排除 .env 和日志文件：

ARGS: -avz --delete --exclude '.env' --exclude '*.log'

服务器端准备工作：

• 必须在目标服务器上安装 Docker 和 Docker Compose。
• 在 /var/admin/InsightReply/server/ 目录下创建 .env 文件（参考 server/.env.example）。

---

2. 前端浏览器扩展构建打包

工作流文件：.gitea/workflows/extension-build.yml 触发条件：当推送代码到 main 分支，且 extension/** 目录有变更时触发。

执行流程：

1. 获取代码并安装 Node.js 20 环境。
2. 依赖与构建：执行 npm install 与 npm run build，编译 Vite/Vue 产物。
3. 打包产物：将生成的 dist 目录打包为 insight-reply-extension.zip。
4. Gitea Release：将生成的 zip 包发布到 Gitea Release。

Tip

后续需要上架 Chrome Web Store 时，可在此流程增加 Chrome Web Store API 上传步骤。

---

3. 版本管理与发布策略

发布类型	触发条件	行为
持续部署	push main + 路径过滤	自动部署到生产/构建扩展
正式发版 (规划中)	推送 v* Tag	创建 Gitea Release + 编译产物附件

推荐版本号规则：

• 后端：v1.0.0、v1.1.0、v1.1.1（语义化版本）
• 扩展：同步跟随后端大版本，manifest.json 中的 version 对齐

---

🔧 Docker 运维规范

容器配置要点

# docker-compose.yml 推荐配置
services:
  insight-reply-server:
    build: .
    container_name: insight-reply-server
    restart: always
    ports:
      - "8080:8080"
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/api/v1/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - insight_network

Important

Healthcheck 说明：当健康检查连续失败 3 次后，Docker 会将容器标记为 unhealthy。配合 restart: always 可自动恢复。

Dockerfile 优化建议

FROM alpine:latest

RUN apk --no-cache add ca-certificates tzdata wget

ENV TZ=Asia/Shanghai

WORKDIR /app

COPY server_bin .
RUN chmod +x server_bin

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=5s \
  CMD wget --spider -q http://localhost:8080/api/v1/health || exit 1

CMD ["./server_bin"]

---

🌐 HTTPS 配置 (反向代理)

生产环境必须使用 HTTPS。推荐使用 Caddy 自动签发 Let's Encrypt 证书：

# Caddyfile 示例
api.insightreply.com {
    reverse_proxy localhost:8080
}

或使用 Nginx：

server {
    listen 443 ssl;
    server_name api.insightreply.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

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

---

🔑 凭证管理 (Secrets)

要使自动化部署正常运行，请在此 Gitea 仓库的 Settings -> Actions -> Secrets 中配置以下环境变量：

Secret 名称	用途
USAARMLOGIN_SSH_KEY	SSH 私钥，用于连接部署目标服务器
GITEA_TOKEN	Gitea API Token，用于发布 Release

---

🔧 服务端运维常用命令 (后端)

部署完成后，如果你需要登录目标服务器进行人工排查：

cd /var/admin/InsightReply/server/

# 查看应用运行状态
docker-compose ps

# 查看应用最新日志
docker-compose logs -f insight-reply-server

# 查看最近 100 行日志
docker-compose logs --tail 100 insight-reply-server

# 重启应用服务
docker-compose restart insight-reply-server

# 强制重新构建并启动
docker-compose up -d --build

# 进入容器内部排查
docker exec -it insight-reply-server sh

---

📊 监控与告警 (规划中)

维度	方案
应用日志	Docker JSON 日志 + 未来接入 Loki 或 Datadog
健康检查	Docker healthcheck + Uptime Kuma
APM	后续考虑接入 Sentry Go SDK
成本监控	api_usage_logs 表追踪 Token 消耗