199 lines
5.6 KiB
Markdown
199 lines
5.6 KiB
Markdown
# 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` 和日志文件：
|
||
> ```yaml
|
||
> 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 运维规范
|
||
|
||
### 容器配置要点
|
||
|
||
```yaml
|
||
# 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 优化建议
|
||
|
||
```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：
|
||
```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 |
|
||
|
||
---
|
||
|
||
## 🔧 服务端运维常用命令 (后端)
|
||
|
||
部署完成后，如果你需要登录目标服务器进行人工排查：
|
||
|
||
```bash
|
||
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 消耗 |
|