From 6e595b4efbf1713bc13808d58b1f0155a9f92211 Mon Sep 17 00:00:00 2001
From: zs <you@example.com>
Date: Sat, 28 Feb 2026 20:25:03 +0800
Subject: [PATCH] docs: add deployment strategy and guidelines

---
 docs/DEPLOYMENT.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 docs/DEPLOYMENT.md

diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..f42839f
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,69 @@
+# InsightReply 部署与发布指南
+
+本文档记录了 InsightReply 项目在生产环境下的自动化持续部署 (CI/CD) 策略。
+由于项目由后端 (Go) 和前端浏览器扩展 (Vue) 组成，为了保证构建速度并解耦故障，我们采用了**前后端分离**的部署工作流。
+
+---
+
+## 🏗 CI/CD 架构方案
+
+我们的自动部署工作流依赖于 Gitea Actions，运行在 `main` 分支的推送动作上。
+
+### 1. 后端自动化部署 (Docker)
+**工作流文件**：`.gitea/workflows/backend-deploy.yml`
+**触发条件**：当推送代码到 `main` 分支，且 `server/**` 目录有变更时触发。
+
+**执行流程**：
+1. **获取代码并安装 Go 1.22 环境**。
+2. **交叉编译**：在 Runner 上编译出适用于 Linux ARM64 的可执行文件 `server_bin`。
+3. **准备部署包**：将可执行文件、`Dockerfile`、`docker-compose.yml` 收集到部署文件夹。
+4. **Rsync 同步**：将文件同步到生产服务器 (`144.24.60.0`) 的 `/var/admin/InsightReply/server/` 目录下。
+5. **平滑重启服务**：通过 SSH 远程执行 `docker-compose up -d --build`，实现不宕机更新。
+
+**服务器端准备工作**：
+* 必须在目标服务器上安装 Docker 和 Docker Compose。
+* （可选）如果在服务端需要提供环境变量给容器，请在 `/var/admin/InsightReply/server/` 目录下创建一个 `.env` 文件。
+
+---
+
+### 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 Artifacts**：将生成的 zip 包上传为当前构建的 Artifacts。
+   *(后续需要上架 Chrome Web Store 时，可在此流程增加 API 上传步骤。)*
+
+---
+
+### 3. 多环境与全局发布 (规划中)
+随着产品演进，当需要打 Tag 发版（如发布 `v1.0.0`）时，我们可以添加一个新的工作流：
+**触发条件**：当推送符合 `v*` 规则的 Tag 时触发。
+**预期行为**：利用 Gitea Release 机制，自动附带当次的前后端编译产物，作为固定资产留存。
+
+## 🔑 凭证管理 (Secrets)
+
+要使自动化部署正常运行，请在此 Gitea 仓库的 `Settings -> Actions -> Secrets` 中配置以下环境变量：
+* `USAARMLOGIN_SSH_KEY`: 用于连接到部署目标服务器 (`144.24.60.0`) 的 SSH 私钥。
+
+---
+
+## 🔧 服务端运维常用命令 (后端)
+
+部署完成后，如果你需要登录目标服务器进行人工排查：
+
+```bash
+cd /var/admin/InsightReply/server/
+
+# 查看应用运行状态
+docker-compose ps
+
+# 查看应用最新日志
+docker-compose logs -f insight-reply-server
+
+# 重启应用服务
+docker-compose restart insight-reply-server
+```