From abe697317c631fac847646d0d4c6220df3b6158b Mon Sep 17 00:00:00 2001
From: Your Name <aa@bb.com>
Date: Mon, 12 Oct 2026 23:45:44 +0800
Subject: [PATCH] docs: design olons server test deployment

---
 ...-12-olons-server-test-deployment-design.md | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-10-12-olons-server-test-deployment-design.md

diff --git a/docs/superpowers/specs/2026-10-12-olons-server-test-deployment-design.md b/docs/superpowers/specs/2026-10-12-olons-server-test-deployment-design.md
new file mode 100644
index 0000000..f0fb3fa
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-12-olons-server-test-deployment-design.md
@@ -0,0 +1,105 @@
+# Olons Server 测试集群部署设计
+
+## 目标
+
+将 `olons_server` 的 `dev` 分支作为前后端一体应用部署到现有 k3s 测试集群，通过 `https://olns-web.118im.com` 对外服务。部署复用现有 PXC、Redis、Traefik、证书体系和 Gitea 镜像仓库，不替换或重启现有 `im-workbench`，也不新增数据库、中间件或持久卷。
+
+## 已确认的源码基线
+
+- 部署分支：`dev`。
+- 验证提交：`96d1de4a95e419433d18be6552422450ec85b10a`。
+- Vue 前端在 Docker 第一阶段构建，产物复制进 Go 运行镜像。
+- Go 服务监听 `6061`，在 `/admin/` 提供前端，在 `/v1/*` 提供业务 API，并暴露 `/healthz` 与 `/metrics`。
+- 前端生产构建、Go 全量测试和完整 Docker 构建均已在隔离环境通过。
+- 应用只允许连接 `olons_admin` 数据库。
+
+## 方案选择
+
+采用独立应用部署，不复用现有 `workbench-system/im-workbench` Deployment。
+
+未采用的方案：
+
+- 覆盖现有 `im-workbench`：会影响已运行的 `/v1/workbench` 服务，风险不可接受。
+- 前后端拆分部署：与仓库现有一体化构建和同源 API 设计不一致，增加不必要的镜像、路由和发布复杂度。
+
+## 应用仓库变更
+
+在 `olons_server` 中完成以下最小变更：
+
+1. 新增部署契约测试，先固定镜像名、Namespace、发布目标和一体化构建要求。
+2. 增加 `.dockerignore`，排除 Git 元数据、本地依赖、构建产物、测试缓存和开发文件。
+3. 保持现有多阶段 Docker 构建；运行镜像仍只包含 Go 二进制、配置模板和前端产物。
+4. 将 Gitea Actions 工作流改为构建并推送 `git.118im.com/im_team/olons-server:test`。
+5. 工作流只滚动更新 `olons-server-system/olons-server`，不得操作现有 `workbench-system/im-workbench`。
+
+## GitOps 资源
+
+在 `im-deploy-config` 中新增独立应用：
+
+- Namespace：`olons-server-system`
+- Deployment：`olons-server`
+- Service：`olons-server`
+- 容器端口：`6061`
+- 副本数：`1`
+- 镜像：`git.118im.com/im_team/olons-server:test`
+- `imagePullPolicy`：`Always`
+- requests：`50m CPU / 64Mi memory`
+- limits：`500m CPU / 256Mi memory`
+- 不创建 PVC
+
+探针：
+
+- startup：TCP `6061`
+- readiness：HTTP `GET /healthz`
+- liveness：TCP `6061`
+
+配置通过 Kubernetes Secret 环境变量注入，Git 仓库只保存 Secret 名称和键引用，不保存任何凭据值。
+
+## 数据库、Redis 与密钥
+
+- MySQL 复用现有 PXC 中的 `olons_admin` 数据库。
+- 使用已有最小权限应用账号；如现有账号权限不足，只补充本应用实际需要的表级权限。
+- Redis 复用现有高可用服务，不修改或重启 Redis。
+- 数据加密密钥与 HMAC 查找密钥从现有兼容配置安全复制到新 Namespace，保证已有敏感数据可解密和检索。
+- 为新服务创建独立 API Key。
+- Redis 会话键使用独立前缀，避免与现有 `im-workbench` 会话冲突。
+- Secret 值不输出到日志、不写入仓库、不写入部署记录。
+
+## 公网路由
+
+在现有 Traefik GitOps 配置中增加高于通配回退规则的专用 Host 路由：
+
+- Host：`olns-web.118im.com`
+- `/admin/`、`/v1/`、`/healthz` 以及前端静态资源均转发到 `olons-server-system/olons-server:6061`
+- `/` 重定向到 `/admin/`
+
+将 `olns-web.118im.com` 加入现有证书资源。域名当前已通过 Cloudflare 解析到集群入口，但专用路由上线前命中的是默认 Web 应用。
+
+## 发布顺序
+
+1. 在两个仓库分别增加失败的部署契约测试。
+2. 完成应用发布配置和 GitOps 清单，使测试转绿。
+3. 运行 Go 测试、前端构建、Docker 构建、应用部署契约测试和 GitOps 测试。
+4. 提交并推送 `olons_server/dev` 与 `im-deploy-config/main`。
+5. 在 `olons-server-system` 创建 Registry Secret 和应用配置 Secret。
+6. 构建并推送 amd64 测试镜像。
+7. 创建或同步 Argo CD Application，等待 Synced/Healthy。
+8. 验证 Pod、Service、Endpoint、数据库、Redis、TLS、页面与 API。
+
+## 验收标准
+
+- Argo CD 应用为 `Synced/Healthy`。
+- Deployment 为 `1/1 Available`，Pod Ready 且无异常重启。
+- 实际运行镜像为本次构建的 `olons-server:test` digest。
+- `/healthz` 在集群内和公网均返回 200。
+- `https://olns-web.118im.com/` 重定向到 `/admin/`。
+- 浏览器打开前端无控制台错误，静态资源全部成功加载。
+- 注册、登录及至少一个需要会话的只读业务接口通过真实请求验证。
+- PXC 和 Redis 保持健康，现有 `im-workbench`、`olons-admin` 及其他 Argo 应用不受影响。
+- 仓库中不存在明文 Secret。
+
+## 回滚
+
+- 应用回滚到前一镜像 digest 或停止新 Deployment，不触碰共享中间件。
+- GitOps 路由异常时回退新增的 Host 路由和证书项，恢复原通配回退行为。
+- 不通过删除数据库记录、清空 Redis 或重启 PXC/Redis实施回滚。