Xiaoxia AI
137 lines
3.2 KiB
Markdown
137 lines
3.2 KiB
Markdown
# 小虾 SaaS 生产资源巡检 Runbook
|
||
|
||
> 状态：生效中
|
||
> 创建时间：2026-06-23
|
||
> 目的：防止生产主机资源过紧导致 SSH/TLS/业务入口卡死。
|
||
|
||
---
|
||
|
||
## 1. 背景
|
||
|
||
2026-06-23 生产 UAT 期间，公开域名曾出现 TLS 握手超时，SSH 出现 banner exchange 超时。后续确认生产主机只有约 1.7GiB 内存且无 swap，短时间系统压力会影响入口层响应。
|
||
|
||
已完成止血：
|
||
|
||
- 添加 `/swapfile` 2GiB。
|
||
- Worker 默认并发限制为 1。
|
||
- `/health` 显示真实发布版本。
|
||
|
||
仍需持续监控：
|
||
|
||
- CPU/load。
|
||
- 可用内存和 swap 使用率。
|
||
- 根分区磁盘使用率。
|
||
- Web/API 健康。
|
||
- 关键容器运行状态。
|
||
- API 版本是否符合期望。
|
||
|
||
---
|
||
|
||
## 2. 巡检脚本
|
||
|
||
脚本路径：
|
||
|
||
```sh
|
||
scripts/production_resource_check.sh
|
||
```
|
||
|
||
默认输出：
|
||
|
||
```sh
|
||
/var/lib/xiaoxia-ci/duty_report.json
|
||
```
|
||
|
||
默认检查：
|
||
|
||
- 5 分钟 load 是否超过 `CPU 数 * 1.5`。
|
||
- 可用内存是否低于 `256MiB`。
|
||
- swap 是否存在，swap 使用率是否超过 `60%`。
|
||
- 根分区磁盘使用率是否超过 `85%`。
|
||
- `http://127.0.0.1:8001/health` 是否可用。
|
||
- `http://127.0.0.1:3002/` 是否可用。
|
||
- 关键生产容器是否 running/healthy。
|
||
|
||
---
|
||
|
||
## 3. 手工运行
|
||
|
||
在生产主机项目目录执行：
|
||
|
||
```sh
|
||
cd /var/lib/xiaoxia-saas-production/repo
|
||
EXPECTED_VERSION=v0.1.15 sh scripts/production_resource_check.sh
|
||
```
|
||
|
||
如果只想生成报告，不指定版本：
|
||
|
||
```sh
|
||
sh scripts/production_resource_check.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 报告格式
|
||
|
||
报告 JSON 包含：
|
||
|
||
- `status`：`healthy` 或 `warning`。
|
||
- `alerts`：需要通知老大的告警。
|
||
- `info`：正常信息。
|
||
- `actions`：自动修复动作，目前保持空数组。
|
||
- `metrics`：load、memory、disk、containers、health 等指标。
|
||
|
||
OpenClaw 心跳可继续读取：
|
||
|
||
```sh
|
||
ssh xiaoxia-server "cat /var/lib/xiaoxia-ci/duty_report.json 2>/dev/null"
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 建议 cron
|
||
|
||
需要老大确认后再启用，不自动创建。
|
||
|
||
建议每 5 分钟巡检一次：
|
||
|
||
```cron
|
||
*/5 * * * * cd /var/lib/xiaoxia-saas-production/repo && EXPECTED_VERSION=v0.1.15 sh scripts/production_resource_check.sh >/var/log/xiaoxia-resource-check.log 2>&1
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 告警处理建议
|
||
|
||
### 6.1 可用内存偏低
|
||
|
||
1. 先查看 `free -h` 和 `docker stats --no-stream`。
|
||
2. 确认 Worker 并发是否仍为 1。
|
||
3. 如 swap 持续大量使用，规划升级生产机规格。
|
||
|
||
### 6.2 磁盘超过 85%
|
||
|
||
1. 先执行只读检查：`du -h -d 1 /var/lib | sort -h`。
|
||
2. 优先清理旧 release tar、旧 runtime images、Docker build cache。
|
||
3. 清理前必须确认可回滚版本和备份。
|
||
|
||
### 6.3 API/Web 健康失败
|
||
|
||
1. 查看 `docker ps`。
|
||
2. 查看容器日志。
|
||
3. 如 API 重建过，Web 必须 force recreate，避免 nginx 静态 upstream 缓存旧 IP。
|
||
|
||
### 6.4 版本不一致
|
||
|
||
1. 确认 `/health` 返回版本。
|
||
2. 确认生产容器镜像 tag。
|
||
3. 确认 Gitea release task 是否完成。
|
||
|
||
---
|
||
|
||
## 7. 长期建议
|
||
|
||
- 生产机升级到至少 4GiB，推荐 8GiB。
|
||
- Gitea 从生产业务机拆分出去。
|
||
- Worker 继续保持并发限制，并按任务队列规模再做动态扩容。
|
||
- 后续接入正式监控告警系统，而不是只依赖心跳读取 JSON。
|