simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: P0遗留修复 + ADR/SOP文档

Browse Source 
- requirements.txt: 添加 passlib[bcrypt] 依赖
- deploy-server/nginx.conf: /ws/ 路径添加 access_log off
- docs/ADRs/: 新增 4 个 ADR 决策记录
- docs/SOPs/: 新增 4 个 SOP 操作规程
This commit is contained in:
Simon
2026-06-15 00:03:11 +08:00
parent eb28a0f2ef
commit 64d6812ec3
11 changed files with 1277 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/SOPs/SOP-001-Gitea部署.md
+96
View File
@@ -0,0 +1,96 @@
# SOP-001: Gitea 部署标准作业流程
**适用**: 新机器 / NAS 迁移 / Gitea 重建
**耗时**: 30-45 分钟
**关联**: [[Gitea部署指南]] / [[ADR-001]]
---
## 1. 前置检查
```bash
# 1.1 NAS 可达
ping 100.85.152.112
# 1.2 SSH 通
ssh simon@100.85.152.112
# 1.3 Tailscale 状态
sudo tailscale status
# 1.4 端口 8418 未占
sudo lsof -i :8418
```
## 2. 装 Gitea 套件
1. DSM → 套件中心
2. 搜 `Gitea` → 安装
3. 装好跳 `http://100.85.152.112:8418/`
## 3. 初始化
1. 创管理员:
- 用户名: `simon`
- 邮箱: 你的
- 密码: 强密码(≥16 位)
2. 数据库: 选 **SQLite3**
3. 站点名: `企微 IT 智能服务台 Git`
4. 立即登录
## 4. 创仓 + token
1. 创仓 `wecom_it_smart_desk`(不勾 README 初始化)
2. 创 simon access token(`simon-admin`)
3. 创 workbuddy-claude user + token(`claude-push`)
## 5. 配 Tailscale Funnel
```bash
sudo tailscale funnel --bg 8418
# 验证
curl -I https://ds923plus.tail58d872.ts.net/
```
## 6. 配分支保护
见 [[ADR-001]] §5 + `scripts/branch-protection.sh`(待写)
## 7. 部署备份
```bash
# 推备份脚本
scp scripts/backup-gitea.sh simon@100.85.152.112:/volume1/docker/wecom-it-desk/scripts/
# 配 cron
ssh simon@100.85.152.112
sudo crontab -e
# 加: 0 3 * * * /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
```
## 8. 本地仓接入
```bash
cd D:\资料\03-项目开发\wecom_it_smart_desk
git remote add origin https://simon@ds923plus.tail58d872.ts.net/simon/wecom_it_smart_desk.git
git push -u origin main # 弹窗输 token
```
## 9. 验证清单
- [ ] Gitea Web UI 正常
- [ ] Funnel 域名正常
- [ ] 创仓 + token 完成
- [ ] 分支保护已配
- [ ] 备份 cron 已配
- [ ] 本地 push 成功
- [ ] workbuddy-claude user 已创 + token 已配
## 10. 出错回滚
| 现象 | 解决 |
|---|---|
| 8418 端口冲突 | Docker 版用 3000 端口 |
| SQLite 写失败 | 检查 `/volume1/@appdata/gitea` 权限 |
| Funnel 域名不通 | `sudo tailscale funnel --bg 8418` 重试 |
| 推 Gitea 401 | 清 wincred,重输 token |
docs/SOPs/SOP-002-Gitea备份恢复.md
+97
View File
@@ -0,0 +1,97 @@
# SOP-002: Gitea 备份恢复标准作业流程
**适用**: 数据丢失应急 / 误操作回滚 / 异地迁移
**耗时**: 5-15 分钟
**关联**: [[Gitea部署指南]] §6/§7
---
## 1. 备份策略
| 项 | 值 | 备注 |
|---|---|---|
| 频率 | 每天 3 点 | cron |
| 保留 | 7 天 | 默认 |
| 路径 | `/volume1/backups/gitea/` | NAS 本地 |
| 异地 | OSS / COS 推 | M-1 风险,待解决 |
| 工具 | `scripts/backup-gitea.sh` | 已写 |
## 2. 手动备份(应急)
```bash
ssh simon@100.85.152.112
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
```
输出:
```
[INFO] === Gitea 备份开始 ===
[OK] 备份配置 app.ini
[OK] SQLite 热备完成
[OK] 仓库 tar 完成
[INFO] === 备份完成 ===
[OK] 最终备份: gitea-backup-20260615-030000.tar.gz
```
## 3. 列出可用备份
```bash
ls -lh /volume1/backups/gitea/
# gitea-backup-20260614-180000.tar.gz 500M
# gitea-backup-20260613-180000.tar.gz 495M
# gitea-backup-20260612-180000.tar.gz 490M
```
## 4. 恢复到 latest
```bash
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh --restore latest
```
**会做**:
1. 停 Gitea 套件
2. 解压备份
3. 覆盖 app.ini / SQLite / repos
4. 启动 Gitea 套件
⚠️ 5 秒倒计时,Ctrl+C 取消
## 5. 恢复到指定时间
```bash
# 看时间戳
ls /volume1/backups/gitea/ | grep gitea-backup
# gitea-backup-20260614-180000.tar.gz
# 恢复
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh --restore 20260614-180000
```
## 6. 验证恢复
1. `http://100.85.152.112:8418/` → 登录 simon
2. 选仓 → 看 commit 历史
3. 验证仓裸仓库大小(`du -sh /volume1/@appdata/gitea/gitea/repos/`)
4. 验证 LFS 数据
## 7. 异地推 OSS(待配)
```bash
# NAS 装 rclone
sudo apt install rclone # 或 synology 套件版
# 配 OSS
rclone config
# 选 aliyun OSS / 腾讯云 COS
# 加 cron
0 4 * * * rclone copy /volume1/backups/gitea/ remote:gitea-backup/ --include "gitea-backup-*.tar.gz"
```
## 8. 故障排查
| 现象 | 原因 | 解决 |
|---|---|---|
| 备份文件大小 0 | SQLite .backup 失败 | 改用文件复制模式(脚本已支持) |
| 恢复后启动失败 | 数据不一致 | 试更早的备份 |
| LFS 数据丢 | 备份脚本漏 LFS | 升级脚本(已修) |
docs/SOPs/SOP-003-推送评审.md
+134
View File
@@ -0,0 +1,134 @@
# SOP-003: 推送评审标准作业流程
**适用**: 任何 commit 推 Gitea / PR 评审 / workbuddy 推送
**耗时**: 5-15 分钟
**关联**: [[CONTRIBUTING]] / [[scripts/pre-commit-check.sh]] / [[风险跟踪表]] 第九/十/十一节
---
## 1. 推送前自检(4 件套)
```bash
cd D:\资料\03-项目开发\wecom_it_smart_desk
# 必跑
bash scripts/pre-commit-check.sh --branch
# 严格模式(任何 warn 失败)
bash scripts/pre-commit-check.sh --branch --strict
```
**通过标准**:
- ✅ PASS ≥ 检查项数
- ⚠️ WARN 看是否影响评审
- ❌ FAIL 必修
## 2. Commit 规范
格式: `<type>(<scope>): <subject>`
| type | 用途 |
|---|---|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `refactor` | 重构(无新功能 / 无 Bug 修复) |
| `docs` | 文档 |
| `chore` | 构建/工具/依赖 |
| `security` | 安全 |
| `perf` | 性能 |
| `test` | 测试 |
**subject**: 中文,祈使句,≤50 字
**body**: 详细说明,每行 ≤72 字
**footer**: 关联 Issue / workbuddy 任务
## 3. 推送流程
### 3.1 workbuddy 推送
1. workbuddy 客户端启动 → 读 `config.json` + `memory/`
2. 接任务(W-1 / W-2 / ...)
3. 写代码 → 本地 commit
4. 推 `feature/xxx` 分支(不走 main,需 PR)
5. 通知 Claude 评审
### 3.2 simon 推送(自己改)
1. 本地改 + commit
2. 推 `feature/xxx` 分支
3. Gitea Web 开 PR
4. 自己 approve + merge(因 `block_admin_merge: false`)
## 4. 评审流程
### 4.1 Claude 评审(主)
1. 收到 workbuddy 推送通知
2. Read 文件 + diff
3. 检查 4 件套
4. 写评审报告 `docs/评审报告/workbuddy-{date}-{topic}.md`
5. 评级:
- 🟢 通过 → 通知合并
- 🟡 留 P1/P2 修 → 评审报告列遗留
- 🔴 拒绝 → 评审报告列阻断
### 4.2 simon 合并
1. 评审通过 → Gitea Web 合并 PR
2. 触发 Gitea Actions CI(待配)
3. CI 绿 → 删 feature 分支
## 5. 评审失败处理
| 评级 | 处理 |
|---|---|
| 🟢 通过 | 合并 + 部署 |
| 🟡 留 P1 | 合并 + 写遗留表 + workbuddy 下一轮修 |
| 🔴 拒绝 | workbuddy 修 → 重新评审 |
## 6. 评审报告格式
`docs/评审报告/workbuddy-{YYYY-MM-DD}-{topic}.md`:
```markdown
# 评审: {topic}
**推送日期**: {date}
**评审日期**: {date}
**评审人**: Claude
**关联 PR**: feature/xxx → main
**关联 commit**: N 个
## ⭐ 一句话结论
...
## 📊 评审结果
| # | 项 | 评级 | 备注 |
|---|---|---|---|
## ✅ 已正确完成
...
## 🟡 半成品(留 P2 优化)
...
## ❌ 错误
...
## 📁 变更清单(N commit)
...
## 🔄 下一轮任务清单
...
## 🔗 推 Gitea 状态
- 远端分支: feature/xxx (HEAD = xxx)
- 评审: ✅ 通过 / 🟡 通过 + 留 / 🔴 拒绝
```
## 7. 不允许
- ❌ 跳过评审直推 main
- ❌ 评审失败强行合并
- ❌ 评审未消化前叠加新功能
- ❌ 改评审报告原文(只加节)
docs/SOPs/SOP-004-应急响应.md
+208
View File
@@ -0,0 +1,208 @@
# SOP-004: 应急响应标准作业流程
**适用**: P0 漏洞 / 数据丢失 / 服务中断 / 安全事件
**响应时间**: 5 分钟响应 + 30 分钟止血 + 24 小时根因
**关联**: [[风险跟踪表]] / [[CONTRIBUTING]] §紧急修复
---
## 1. 事件分级
| 等级 | 场景 | 响应时间 |
|---|---|---|
| 🔴 **P0 紧急** | P0 鉴权漏洞 + 数据泄露 + 服务全停 | 5 min |
| 🟠 **P1 高** | P1 功能故障 + 单服务降级 | 30 min |
| 🟡 **P2 中** | P2 性能 / UI 问题 | 4 h |
| 🟢 **P3 低** | 体验优化 | 1 周 |
## 2. P0 应急流程(5 min 响应)
### 2.1 立即止血
1. **服务降级**:
- 关闭外网访问:`sudo iptables -A INPUT -p tcp --dport 8418 -j DROP`
- 或:套件中心停 Gitea
- 或:Nginx `deny all;`
2. **停可疑服务**:
- 停后端:`docker compose stop backend`
- 停 WebSocket:`docker compose stop nginx`(整体停)
3. **保留现场**:
- 不删任何文件
- 复制 log 到 `/tmp/incident-{timestamp}/`
- 截图
### 2.2 通知
1. 微信 / 电话通知项目负责人 宋献
2. 邮件群发:`wecom-it-desk-incident@servyou-it.com`
3. 建应急群
### 2.3 临时回滚
```bash
# 1. 找上一个稳定版本
git tag -l # 看 release tag
git log --oneline -20 # 看 commit 历史
# 2. 回滚到上一个 commit
git revert HEAD # 生成新 commit 撤销
# 或
git reset --hard HEAD~1 # 强回滚(慎用)
# 3. 强推(临时,需 admin 权限)
git push -f origin main
```
## 3. 根因分析(24h 内)
### 3.1 收集证据
```bash
# 后端日志
docker logs backend --tail 1000 > /tmp/incident/backend.log
# nginx 错误日志
sudo cat /var/log/nginx/error.log > /tmp/incident/nginx-error.log
# Gitea 日志
sudo synopkg log Gitea > /tmp/incident/gitea.log
```
### 3.2 5 Why 分析
```markdown
# 5 Why 分析
**事件**: 坐席登录无鉴权
**Why 1**: agents.py login() 函数没用 Depends(get_current_*)
**Why 2**: workbuddy 加新端点时没跑 pre-commit-check
**Why 3**: pre-commit-check 不在 git commit hook 里
**Why 4**: 没用 pre-commit 框架(只是脚本)
**Why 5**: 流程规范没强制(评审可跳)
**根因**: 流程规范未自动化
**对策**: 加 pre-commit + Gitea Actions 强制
```
### 3.3 写事故报告
`docs/事故报告/incident-{date}-{topic}.md`:
```markdown
# 事故报告: {topic}
**日期**: {date}
**等级**: 🔴 P0
**响应人**: {name}
**持续**: X 分钟
## 1. 时序
| 时刻 | 事件 |
|---|---|
## 2. 影响范围
- 用户: X 人受影响
- 数据: 是否泄露
- 服务: 停 X 分钟
## 3. 5 Why 根因
...
## 4. 修复 commit
- {commit-hash}
- {commit-message}
## 5. 防止再发
- [ ] 加 pre-commit hook
- [ ] 加 Gitea Actions 强制
- [ ] 更新风险跟踪表
- [ ] 评审 SOP 更新
```
## 4. P1 应急流程(30 min 响应)
### 4.1 评估
- 是否影响生产用户?
- 是否有降级方案?
### 4.2 止血
- 单服务降级(关问题服务,其它继续)
- 临时禁用相关端点(nginx `location /api/v1/xxx { return 503; }`)
### 4.3 修复
- hotfix 分支(从 main 拉)
- PR + 评审 + 合并 + 部署
## 5. 数据丢失应急
### 5.1 Gitea 数据丢失
1. **别再操作** Gitea(避免覆盖)
2. 跑 `scripts/backup-gitea.sh --restore latest`
3. 验证:仓 commit 数 / token 列表
4. 不行:试更早备份
### 5.2 生产数据库丢失
1. 立即停所有服务(避免写入)
2. 看 PostgreSQL 数据目录:`/var/lib/postgresql/data`
3. 走 PITR(Point In Time Recovery)
4. 启用只读模式 + 通知用户
## 6. 安全事件
### 6.1 Token 泄露
1. **立即撤销** token:
```bash
curl -X DELETE -H "Authorization: token $ADMIN_TOKEN" \
"http://100.85.152.112:8418/api/v1/users/{username}/tokens"
```
2. 清 wincred 缓存
3. 创新 token + 配新凭据
4. 改所有引用旧 token 的脚本/配置
5. 评审日志:谁访问过 / 推过什么
### 6.2 入侵检测
1. 看 `auth.log` / `nginx-access.log` / `backend.log`
2. 找异常 IP / 时间 / 路径
3. 封 IP:`sudo iptables -A INPUT -s {ip} -j DROP`
4. 改所有密码 / 凭据
5. 走事件调查流程
## 7. 通讯模板
### 7.1 启动应急
```
【应急启动】{事件简述}
等级: 🔴 P0
影响: {用户/数据/服务}
已开始止血:{动作}
请相关人:{人名} 立即响应
群: {微信群名}
```
### 7.2 解决通知
```
【已解决】{事件简述}
持续: X 分钟
修复: {commit-hash}
根因: {5 Why 结论}
防止再发: {动作}
报告: docs/事故报告/{file}.md
```
## 8. 联系
| 角色 | 联系人 |
|---|---|
| 项目负责人 | 宋献(企业微信 / 手机) |
| 运维 | IT 支持组 |
| NAS / Gitea | 群晖技术支持 |
| Tailscale | tailscale.com/support |