long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: project docs, scripts, deployment configs, and evidence

Browse Source
This commit is contained in:
long-agent
2026-04-02 11:22:17 +08:00
parent 4718980ab5
commit bbeeb63dfa
396 changed files with 165018 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs/guides/ALERTING_ONCALL_RUNBOOK.md Normal file
View File

@@ -0,0 +1,87 @@
# 告警与值班 Runbook
更新日期：2026-03-24
## 目标
- 统一用户管理系统的告警分级、响应时限、升级路径与恢复验证动作
- 让“有告警规则”转变为“有处理流程、可追责、可复盘”
## 当前边界
- 仓库内已存在 Prometheus 告警规则与 Alertmanager 路由配置
- 仓库内已补齐本地结构校验材料
- 仓库内已补齐 Alertmanager 模板渲染路径：
- [`deployment/alertmanager/alertmanager.yml`](/D:/project/deployment/alertmanager/alertmanager.yml)
- [`deployment/alertmanager/alertmanager.env.example`](/D:/project/deployment/alertmanager/alertmanager.env.example)
- [`scripts/ops/render-alertmanager-config.ps1`](/D:/project/scripts/ops/render-alertmanager-config.ps1)
- 仓库内已补齐严格的 live-delivery drill 入口：
- [`scripts/ops/drill-alertmanager-live-delivery.ps1`](/D:/project/scripts/ops/drill-alertmanager-live-delivery.ps1)
- the script fails closed on unresolved placeholders, `example.*` values, and placeholder secrets
- the script stores only redacted config output and masked recipient information in evidence artifacts
- 当前仍未闭环的是外部通知通道真实接入证据；需要把模板变量渲染为真实联系人、真实 SMTP/通知通道和真实密钥来源
## 严重级别
- `critical`
- 典型场景：高错误率、数据库连接池耗尽、高内存
- 目标响应：5 分钟内确认，15 分钟内给出处置方向
- `warning`
- 典型场景：高响应时间、高登录失败率、低缓存命中率
- 目标响应：15 分钟内确认，60 分钟内恢复或降级
- `info`
- 典型场景：在线用户数偏低、请求量异常
- 目标响应：工作时间内确认，纳入趋势分析
## 标准处理流程
1. 接警后确认 `alertname`、`severity`、`service`、开始时间和当前值。
2. 检查基础健康：
- `GET /health`
- `GET /health/ready`
- `GET /api/v1/auth/capabilities`
3. 如涉及登录/后台主链路，执行：
- `cd frontend/admin && npm.cmd run e2e:full:win`
4. 对照指标判断是瞬时抖动、配置错误、发布回归还是依赖故障。
5. 若为发布回归，直接进入回滚流程：
- [`ROLLBACK_RUNBOOK.md`](/D:/project/docs/guides/ROLLBACK_RUNBOOK.md)
6. 故障恢复后记录根因、影响范围、恢复时间、后续永久修复项。
## 升级路径
1. 一线值班先确认告警是否真实、是否影响核心用户路径。
2. `critical` 未在 15 分钟内止血，升级到应用负责人和平台负责人。
3. 涉及数据一致性、备份恢复、跨版本回滚时，升级到 DBA/平台发布负责人。
4. 需要对外沟通时，由服务 owner 输出统一事故通报。
## 发布前检查
- 告警规则结构校验通过
- Alertmanager 路由接收者已替换为真实联系人与真实 SMTP/通知通道
- Alertmanager 模板已完成渲染，且渲染产物不再包含 `${ALERTMANAGER_*}` 未解析变量
- live-delivery drill 已使用真实 env 注入执行成功，并形成红acted evidence
- 最新基线低于阈值，不存在“发布即告警”
- 回滚脚本和备份恢复脚本可执行
## 本地校验
- 告警包校验脚本：
- [`scripts/ops/validate-alerting-package.ps1`](/D:/project/scripts/ops/validate-alerting-package.ps1)
- 告警渲染演练脚本：
- [`scripts/ops/drill-alertmanager-render.ps1`](/D:/project/scripts/ops/drill-alertmanager-render.ps1)
- 告警真实投递演练脚本：
- [`scripts/ops/drill-alertmanager-live-delivery.ps1`](/D:/project/scripts/ops/drill-alertmanager-live-delivery.ps1)
- use a real env file or process environment; `alertmanager.env.example` is expected to fail closed and cannot be used as closure evidence
- 最新校验证据：
- 校验执行后会生成 `docs/evidence/ops/<date>/alerting/ALERTING_PACKAGE_<timestamp>.md`
- 渲染演练执行后会生成 `docs/evidence/ops/<date>/alerting/<timestamp>/ALERTMANAGER_RENDER_DRILL.md`
- live-delivery drill 执行后会生成 `docs/evidence/ops/<date>/alerting/<timestamp>/ALERTMANAGER_LIVE_DELIVERY_DRILL.md`
## 关联材料
- 本地观测基线：
- [`docs/evidence/ops/2026-03-24/observability/LOCAL_BASELINE_20260324-090637.md`](/D:/project/docs/evidence/ops/2026-03-24/observability/LOCAL_BASELINE_20260324-090637.md)
- 回滚 runbook：
- [`ROLLBACK_RUNBOOK.md`](/D:/project/docs/guides/ROLLBACK_RUNBOOK.md)
- 项目当前真实状态：
- [`REAL_PROJECT_STATUS.md`](/D:/project/docs/status/REAL_PROJECT_STATUS.md)

297
docs/guides/GO_INSTALLATION_GUIDE.md Normal file
View File

@@ -0,0 +1,297 @@
# Go环境安装指南
## 📥 步骤1: 下载Go
访问Go官方网站: https://golang.org/dl/
### Windows版本选择
根据您的系统选择对应的版本：
| 系统架构 | 下载链接 |
|---------|---------|
| 64位Windows（推荐） | https://go.dev/dl/go1.23.6.windows-amd64.msi |
| 32位Windows | https://go.dev/dl/go1.23.6.windows-386.msi |
**推荐版本**: Go 1.23.6 或更高版本
---
## 🚀 步骤2: 安装Go
### 方法1: MSI安装包（推荐）
1. 双击下载的MSI文件（如 `go1.23.6.windows-amd64.msi`）
2. 在安装向导中点击 "Next"
3. 接受许可协议
4. 选择安装路径（默认 `C:\Go` 即可）
5. 点击 "Install" 开始安装
6. 等待安装完成
7. 点击 "Finish" 完成安装
### 方法2: ZIP压缩包
1. 下载ZIP文件（如 `go1.23.6.windows-amd64.zip`）
2. 解压到 `C:\` 目录
3. 会得到 `C:\go` 目录
4. 手动配置环境变量（见下一步）
---
## 🔧 步骤3: 配置环境变量
### 自动配置（MSI安装包）
MSI安装包通常会自动配置以下环境变量：
- `GOROOT`: Go安装目录（如 `C:\Go`）
- `GOPATH`: Go工作目录（默认 `%USERPROFILE%\go`）
- `PATH`: 添加 `%GOROOT%\bin` 和 `%GOPATH%\bin`
**如果自动配置失败，手动配置：**
### 手动配置
1. 右键点击 "此电脑" → "属性"
2. 点击 "高级系统设置"
3. 点击 "环境变量"
4. 在 "系统变量" 中操作：
#### 添加 GOROOT
1. 点击 "新建"
2. 变量名: `GOROOT`
3. 变量值: `C:\Go`（或您的实际安装路径）
4. 点击 "确定"
#### 添加 GOPATH
1. 点击 "新建"
2. 变量名: `GOPATH`
3. 变量值: `%USERPROFILE%\go`
4. 点击 "确定"
#### 编辑 PATH
1. 找到 "Path" 变量
2. 点击 "编辑"
3. 点击 "新建"
4. 添加: `%GOROOT%\bin`
5. 再次点击 "新建"
6. 添加: `%GOPATH%\bin`
7. 点击 "确定" 保存
---
## ✅ 步骤4: 验证安装
### 重启命令行
**重要**: 必须重新打开PowerShell或命令提示符，环境变量才能生效！
### 检查Go版本
打开新的PowerShell窗口，运行：
```powershell
go version
```
**预期输出**:
```
go version go1.23.6 windows/amd64
```
### 检查Go环境
```powershell
go env
```
**预期输出**: 显示完整的Go环境配置
### 验证关键路径
```powershell
# 检查GOROOT
$env:GOROOT
# 检查GOPATH
$env:GOPATH
# 检查PATH是否包含Go
$env:PATH -split ';' | Select-String "go"
```
---
## 🧪 步骤5: 测试Go
### 创建测试程序
```powershell
# 创建临时目录
mkdir $env:USERPROFILE\test-go
cd $env:USERPROFILE\test-go
# 创建测试文件
@'
package main
import "fmt"
func main() {
fmt.Println("Hello, Go is installed correctly!")
}
'@ | Out-File -FilePath hello.go -Encoding utf8
# 运行测试程序
go run hello.go
```
**预期输出**:
```
Hello, Go is installed correctly!
```
---
## 🔍 故障排查
### 问题1: go命令找不到
**错误信息**:
```
'go' 不是内部或外部命令
```
**解决方案**:
1. 检查Go是否安装成功
```powershell
Test-Path C:\Go\bin\go.exe
```
2. 检查环境变量
```powershell
$env:PATH -split ';' | Select-String "Go"
```
3. 如果PATH中没有Go，重新配置环境变量
4. **重启命令行窗口**
### 问题2: Go版本太旧
**检查**:
```powershell
go version
```
如果版本 < 1.23，需要重新安装新版本。
### 问题3: 权限问题
如果安装时提示权限不足：
1. 以管理员身份运行MSI安装包
2. 右键点击MSI文件 → "以管理员身份运行"
### 问题4: PATH不生效
**解决方案**:
1. 完全关闭所有命令行窗口
2. 重新打开PowerShell
3. 运行:
```powershell
refreshenv
```
或者注销后重新登录
---
## 📝 安装后配置
### 配置Go模块代理（中国用户推荐）
```powershell
# 设置Go模块代理（加速下载）
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=off
```
### 验证代理设置
```powershell
go env GOPROXY
```
预期输出: `https://goproxy.cn,direct`
---
## 🎯 下一步
安装完成后，请继续执行：
### 1. 验证项目编译
```powershell
cd D:\project
go mod verify
go build ./cmd/server
```
### 2. 运行测试
```powershell
go test ./... -v
```
### 3. 启动项目
```powershell
go run cmd/server/main.go
```
### 4. 测试API
```powershell
# 健康检查
Invoke-RestMethod http://localhost:8080/health
```
---
## ✅ 安装检查清单
完成Go安装后，请确认：
- [ ] 下载并安装了Go 1.23+
- [ ] 环境变量已配置（GOROOT, GOPATH, PATH）
- [ ] 重启了命令行窗口
- [ ] `go version` 命令正常工作
- [ ] `go env` 命令正常工作
- [ ] 测试程序运行成功
- [ ] （可选）配置了Go模块代理
---
## 📞 遇到问题？
如果遇到安装问题：
1. **查看官方文档**: https://golang.org/doc/install
2. **检查系统要求**: Windows 7 或更高版本
3. **检查磁盘空间**: 至少 500MB 可用空间
4. **检查权限**: 确保有管理员权限
---
## 🎉 安装完成
完成以上步骤后，Go环境就安装完成了！
请告诉我"Go安装完成"，我将继续执行：
1. 验证项目编译
2. 运行测试
3. 完成所有功能
4. 确认迁移完成后删除C盘文件
---
**安装预计时间**: 10-20分钟

135
docs/guides/GO_TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,135 @@
# Go安装问题诊断
## 🔍 诊断结果
**Go 1.26.1 已安装** 到 `C:\Program Files\Go\`
**问题**: Go命令无法在当前执行环境中运行
**可能原因**:
1. 环境变量PATH未更新
2. 命令行窗口未重启
3. Go.exe文件权限问题
---
## ✅ 手动验证步骤
### 步骤1: 完全关闭所有命令行窗口
关闭所有：
- PowerShell窗口
- 命令提示符窗口
- VS Code终端
- 任何IDE的终端
### 步骤2: 重新打开PowerShell
按 `Win + X`，选择 "Windows PowerShell" 或 "Terminal"
### 步骤3: 验证Go
运行命令：
```powershell
go version
```
**预期输出**:
```
go version go1.26.1 windows/amd64
```
如果看到版本号，说明安装成功！
### 步骤4: 验证环境变量
```powershell
go env
```
应该显示完整的Go环境配置。
---
## 🔧 如果仍然失败
### 方法1: 手动添加PATH
1. 右键 "此电脑" → "属性"
2. "高级系统设置" → "环境变量"
3. 在 "系统变量" 中找到 "Path"
4. 点击 "编辑"
5. 点击 "新建"
6. 添加: `C:\Program Files\Go\bin`
7. 点击 "确定" 保存所有窗口
### 方法2: 临时使用完整路径
```powershell
& "C:\Program Files\Go\bin\go.exe" version
```
### 方法3: 使用新的PowerShell窗口
1. 按 `Win + R`
2. 输入 `powershell`
3. 按回车
4. 运行 `go version`
---
## ✅ 验证成功后
一旦 `go version` 命令正常工作，请告诉我：
**"Go验证成功"**
然后我将立即继续：
1. ✅ 验证项目编译
2. ✅ 运行项目测试
3. ✅ 完成所有功能实现
4. ✅ 确认迁移完成后删除C盘文件
---
## 🎯 快速验证脚本
创建新文件 `verify_go.bat`:
```batch
@echo off
echo Verifying Go installation...
echo.
"C:\Program Files\Go\bin\go.exe" version
echo.
if %errorlevel% == 0 (
echo [SUCCESS] Go is working!
echo.
echo Please tell WorkBuddy: "Go验证成功"
) else (
echo [ERROR] Go is not working
echo.
echo Please try:
echo 1. Close all command windows
echo 2. Open new PowerShell
echo 3. Run: go version
)
pause
```
运行:
```batch
verify_go.bat
```
---
## 💡 提示
**如果 `go version` 在新的PowerShell窗口中正常工作**，说明安装成功，只是之前的命令行窗口需要刷新环境变量。
**请重新打开PowerShell窗口并运行 `go version` 验证！**
验证成功后告诉我，我将继续后续工作。

58
docs/guides/ROLLBACK_RUNBOOK.md Normal file
View File

@@ -0,0 +1,58 @@
# 回滚 Runbook
更新日期：2026-03-24
## 适用范围
- 当前仓库的本地/单节点发布回滚
- 配置错误、发布态校验失败、健康检查失败、认证主链路异常等需要快速回退的场景
## 触发条件
- `/health/ready` 连续失败
- 发布后 `auth/capabilities`、登录、后台关键页面出现回归
- 新版本被 release 模式配置校验拒绝启动
- 5xx、认证失败、权限异常等核心指标显著恶化
## 前置要求
- 保留上一版稳定配置与制品路径
- 发布前已完成数据库备份
- 当前环境可通过 `UMS_CONFIG_PATH` 切换配置
- 健康检查与认证探针可访问：
- `GET /health`
- `GET /health/ready`
- `GET /api/v1/auth/capabilities`
## 标准步骤
1. 立即冻结当前发布，停止继续变更。
2. 保存候选版本 stdout/stderr、配置文件、探针失败结果。
3. 停止候选实例。
4. 将 `UMS_CONFIG_PATH` 指向上一版稳定配置，并启动上一版稳定制品。
5. 验证回滚后的实例：
- `/health` 返回成功
- `/health/ready` 返回成功
- `/api/v1/auth/capabilities` 返回符合预期
- 如涉及前端链路，执行 `cd frontend/admin && npm.cmd run e2e:full:win`
6. 记录回滚原因、影响范围、恢复时间和后续修复动作。
## 数据边界
- 如果问题仅是配置或应用层回归，应优先执行配置/制品回滚。
- 如果怀疑数据损坏，不应直接做 schema downgrade；应先执行备份恢复流程并评估数据影响。
- 当前仓库已经完成的是本地配置/制品回滚演练，不等于历史版本之间的数据库降级兼容性证明。
## 本地演练
- 演练脚本：
- [`scripts/ops/drill-local-rollback.ps1`](/D:/project/scripts/ops/drill-local-rollback.ps1)
- 最新演练证据：
- [`docs/evidence/ops/2026-03-24/rollback/20260324-084928/ROLLBACK_DRILL.md`](/D:/project/docs/evidence/ops/2026-03-24/rollback/20260324-084928/ROLLBACK_DRILL.md)
## 关联材料
- 备份恢复演练：
- [`docs/evidence/ops/2026-03-24/backup-restore/20260324-072353/BACKUP_RESTORE_DRILL.md`](/D:/project/docs/evidence/ops/2026-03-24/backup-restore/20260324-072353/BACKUP_RESTORE_DRILL.md)
- 配置与环境隔离演练：
- [`docs/evidence/ops/2026-03-24/config-isolation/20260324-084915/CONFIG_ENV_ISOLATION_DRILL.md`](/D:/project/docs/evidence/ops/2026-03-24/config-isolation/20260324-084915/CONFIG_ENV_ISOLATION_DRILL.md)

162
docs/guides/TESTING.md Normal file
View File

@@ -0,0 +1,162 @@
# 测试指南
更新日期：2026-03-24
本文档只描述当前项目已落地、已验证的测试路径。
## 1. 环境要求
- Go 1.25+
- Node.js 20+
- Windows PowerShell 环境下，如 `npm.ps1` 被策略拦截，请使用 `npm.cmd`
如果本机 Go 全局缓存目录受限，建议在执行 Go 命令前显式指定本地缓存目录：
```powershell
$env:GOMODCACHE = "D:\project\.cache\gomod"
$env:GOPATH = "D:\project\.cache\gopath"
$env:GOCACHE = "D:\project\.cache\go-build"
```
## 2. 后端验证
### 单元与集成测试
```powershell
go test ./... -count=1
```
如需执行默认回归之外的大并发压力测试，请显式开启：
```powershell
$env:RUN_STRESS_TESTS = "1"
go test ./... -count=1
```
### 静态检查
```powershell
go vet ./...
```
### 构建验证
```powershell
go build ./cmd/server
```
### 健康检查验证
启动服务后可验证：
```powershell
curl http://localhost:8080/health
curl http://localhost:8080/health/live
curl http://localhost:8080/health/ready
```
说明：
- `/health` 兼容历史探针，语义等同 readiness
- `/health/live` 只验证进程存活
- `/health/ready` 会检查数据库可用性
## 3. 前端验证
在 [`frontend/admin`](/D:/project/frontend/admin) 下执行：
```powershell
npm.cmd run test:run
npm.cmd run lint
npm.cmd run build
```
当前已补充并验证的前端重点包括：
- 认证服务契约测试
- 登录页按 `auth/capabilities` 动态展示登录方式
- 忘记密码入口按 `password_reset` 能力显隐
## 4. 真实浏览器验证
当前环境下 `playwright test` runner 会因 `spawn EPERM` 受限，因此真实浏览器验证主路径不是 runner，而是“外部启动真实浏览器 + Playwright 库经 CDP 接管”。
当前 CDP 验证脚本会把以下信号视为失败：
- console error
- native dialog
- popup page
- page error
- request failure
- `401` 响应
- 被前端 `window` guard 拦截的 `alert/confirm/prompt/open`
Windows 下 `e2e:full:win` 与 `e2e:auth-smoke:win` 都会自动把 Go 缓存写到 `%TEMP%\\ums-e2e-cache`，避免工作区权限问题。
### 全量真实浏览器 E2E
```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:full:win
```
当前覆盖：
- `login-surface`
- 登录页能力展示
- 未登录访问受保护路由重定向
- `auth-workflow`
- 真实登录
- 用户列表
- 用户详情抽屉
- 分配角色弹窗
- 角色页
- 分配权限弹窗
- Dashboard
- 真实登出与登出后重定向
- `responsive-login`
- desktop / tablet / mobile 视口渲染与横向溢出检查
- `desktop-mobile-navigation`
- 桌面侧边导航
- 移动端抽屉导航
### 补充页面与路由 smoke
```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:smoke:win
```
当前覆盖：
- 未登录访问 `/dashboard`、`/users` 会重定向到 `/login`
- 登录页按后端能力动态显示可用登录方式
- 忘记密码入口按能力显隐
- 多视口下页面可正常渲染
### 补充真实认证链路 smoke
```powershell
cd D:\project\frontend\admin
npm.cmd run e2e:auth-smoke:win
```
当前覆盖：
- 从受保护路由跳转到登录页
- 真实登录后回到目标页面
- 用户列表加载
- 用户详情抽屉打开
- 分配角色弹窗打开
- 角色管理页跳转
- 分配权限弹窗打开
- Dashboard 加载
- 真实登出后再次访问受保护页面会被重定向到登录页
## 5. 边界说明
- 当前支持的 CDP 路径已经是浏览器级真实验证，不是 DOM mock。
- 当前支持的 CDP 路径不是完整 OS 级自动化。
- 不覆盖系统文件选择器、原生桌面弹窗、操作系统级权限窗口等行为。
- `e2e:full:win` 是当前受支持的主验收路径；`smoke` 脚本保留为补充诊断，不代表产品运行时仍依赖 smoke。
- 测试层的 smoke 脚本和 mock helper 是允许的，但它们不应继续进入产品运行时。
- 认证相关接口当前会统一返回 `Cache-Control: no-store` 等响应头；如果在抓包或浏览器开发者工具中看不到缓存命中，这是预期行为。