From 77f4eb1579adbb9abcf7e4bba86bcb32d45f6df6 Mon Sep 17 00:00:00 2001 From: bizwings Date: Wed, 24 Jun 2026 12:14:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(knowledge):=20opengineer=20-=20=E5=88=9B?= =?UTF-8?q?=E5=BB=BA=E8=BF=90=E7=BB=B4/=E8=A7=84=E8=8C=83=E9=A2=86?= =?UTF-8?q?=E5=9F=9F=E7=9F=A5=E8=AF=86=E6=9D=A1=E7=9B=AE(=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=B5=81=E7=A8=8B/=E6=95=85=E9=9A=9C=E6=8E=92?= =?UTF-8?q?=E6=9F=A5/=E6=9C=8D=E5=8A=A1=E5=99=A8=E8=BF=90=E7=BB=B4?= =?UTF-8?q?=E6=A0=87=E5=87=86)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: multica-agent --- knowledge/README.md | 2 + knowledge/技术/README.md | 4 +- knowledge/规范/README.md | 25 +++ knowledge/运维/README.md | 27 +++ knowledge/运维/故障排查手册_v1.0.md | 274 ++++++++++++++++++++++++++ knowledge/运维/服务器运维标准_v1.0.md | 177 +++++++++++++++++ knowledge/运维/部署流程_v1.0.md | 202 +++++++++++++++++++ 7 files changed, 710 insertions(+), 1 deletion(-) create mode 100644 knowledge/规范/README.md create mode 100644 knowledge/运维/README.md create mode 100644 knowledge/运维/故障排查手册_v1.0.md create mode 100644 knowledge/运维/服务器运维标准_v1.0.md create mode 100644 knowledge/运维/部署流程_v1.0.md diff --git a/knowledge/README.md b/knowledge/README.md index 5c5b026..7e7167b 100644 --- a/knowledge/README.md +++ b/knowledge/README.md @@ -12,8 +12,10 @@ | [产品/](产品/) | PRD、需求分析 | 沈路明 (productmanager) | — | | [技术/](技术/) | 开发规范、代码审查 | 徐聪 (costcodev) | — | | [设计/](设计/) | UI设计、品牌规范 | 苏绘锦 (designer) | — | +| [运维/](运维/) | 部署流程、故障排查、服务器运维 | 严维序 (opengineer) | 3 | | [运营/](运营/) | 活动策划、数据分析 | 陆怀瑾 (coo) | — | | [行政/](行政/) | 合同、报销流程 | 刘诗妮 (secretary) | — | +| [规范/](规范/) | 运维标准、安全基线、合规要求 | 严维序 (opengineer) | — | ## 知识条目格式 diff --git a/knowledge/技术/README.md b/knowledge/技术/README.md index c71942c..8aa764c 100644 --- a/knowledge/技术/README.md +++ b/knowledge/技术/README.md @@ -5,7 +5,9 @@ ## 知识范围 -涵盖开发规范、代码审查、架构设计、部署运维、技术选型等技术团队知识。 +涵盖开发规范、代码审查、架构设计、技术选型等技术团队核心知识。 + +> ⚠️ 部署运维知识已迁移至 [运维/](../运维/) 领域。 ## 条目清单 diff --git a/knowledge/规范/README.md b/knowledge/规范/README.md new file mode 100644 index 0000000..5fba1d6 --- /dev/null +++ b/knowledge/规范/README.md @@ -0,0 +1,25 @@ +# 规范领域知识 + +**责任人**：严维序（opengineer） +**审核人**：陆怀瑾（coo） + +## 知识范围 + +涵盖运维规范、安全标准、合规要求等规范类知识条目，支撑团队标准化运作。 + +## 条目清单 + +| 文件名 | 说明 | 状态 | +|--------|------|------| +| [服务器运维标准_v1.0.md](../运维/服务器运维标准_v1.0.md) | 服务器巡检、监控、备份运维标准 | 见运维域 | + +## 待建设 + +- 数据库运维标准 +- 安全审计基线 +- 数据合规处理流程 + +--- + +> 维护者：严维序（opengineer） +> 最后更新：2026-06-24 \ No newline at end of file diff --git a/knowledge/运维/README.md b/knowledge/运维/README.md new file mode 100644 index 0000000..509110c --- /dev/null +++ b/knowledge/运维/README.md @@ -0,0 +1,27 @@ +# 运维领域知识 + +**责任人**：严维序（opengineer） +**审核人**：陆怀瑾（coo） + +## 知识范围 + +涵盖服务器运维、部署流程、故障排查、监控配置、安全保障等运维团队核心知识。 + +## 条目清单 + +| 文件名 | 说明 | 状态 | +|--------|------|------| +| [部署流程_v1.0.md](部署流程_v1.0.md) | 服务部署 SOP 与变更管理流程 | ✅ | +| [故障排查手册_v1.0.md](故障排查手册_v1.0.md) | 常见故障定位与处置方案 | ✅ | +| [服务器运维标准_v1.0.md](服务器运维标准_v1.0.md) | 服务器巡检、监控、备份运维标准 | 🆕 | + +## 待建设 + +- 数据库运维指南 +- 安全加固检查清单 +- 灾备与应急恢复预案 + +--- + +> 维护者：严维序（opengineer） +> 最后更新：2026-06-24 \ No newline at end of file diff --git a/knowledge/运维/故障排查手册_v1.0.md b/knowledge/运维/故障排查手册_v1.0.md new file mode 100644 index 0000000..faf3cec --- /dev/null +++ b/knowledge/运维/故障排查手册_v1.0.md @@ -0,0 +1,274 @@ +# 故障排查手册 + +## 元数据 + +| 属性 | 值 | +|------|-----| +| **领域** | 运维 | +| **责任人** | 严维序（opengineer） | +| **版本** | v1.0 | +| **创建日期** | 2026-06-24 | +| **最后更新** | 2026-06-24 | +| **标签** | 故障排查, 运维, 排障 | + +## 概述 + +本手册汇总 BizWings 环境中常见的系统与服务故障定位方法和修复方案。覆盖 SSH 连接、Nginx、数据库、磁盘、Docker 等核心场景。 + +--- + +## 一、SSH 连接故障 + +### 1.1 连接超时 + +```bash +# 诊断步骤 +ssh -vvv root@ -p # 查看详细连接日志 +ping # 检查网络连通性 +nmap -p # 检查端口状态 +``` + +**常见原因**： +- 目标服务器防火墙未开放端口 +- 源 IP 未加入白名单 +- 服务器负载过高，sshd 响应慢 + +**解决方案**： +1. 检查服务器防火墙：`iptables -L -n` 或 `ufw status` +2. 检查 sshd 是否运行：`systemctl status sshd` +3. 检查负载：`top -n1 | head -5` + +### 1.2 认证失败 + +```bash +# 诊断步骤 +ssh -p root@ # 尝试密码登录 +# Permission denied (publickey,password) 提示 +``` + +**常见原因**： +- 密码错误（检查 TOOLS.md 中记录） +- SSH 密钥认证配置错误 +- `/etc/ssh/sshd_config` 中 `PasswordAuthentication no` + +**解决方案**： +1. 确认密码与 TOOLS.md 一致 +2. 检查 `sshd_config`：`grep PasswordAuthentication /etc/ssh/sshd_config` +3. 临时允许密码登录：`sed -i 's/PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config && systemctl reload sshd` + +--- + +## 二、Nginx 服务异常 + +### 2.1 Nginx 启动失败 / 卡在 activating + +```bash +# 诊断步骤 +systemctl status nginx # 查看状态 +journalctl -u nginx --no-pager -n 50 # 查看日志 +nginx -t # 配置语法检查 +``` + +**根因（经验）**：进程残留导致端口占用 + +```bash +# 修复 +pkill -9 nginx # 强制清理残留进程 +sleep 2 +systemctl start nginx # 重新启动 +systemctl status nginx # 确认状态 +``` + +### 2.2 502 Bad Gateway + +```bash +# 诊断步骤 +curl -I http://localhost: # 检查上游服务 +ss -tlnp | grep # 检查端口监听 +systemctl status # 检查上游进程 +``` + +**常见原因**： +- 上游服务未启动或崩溃 +- 连接池耗尽 + +**解决方案**： +1. 重启上游服务：`systemctl restart ` +2. 检查 `upstream` 配置是否正确 + +### 2.3 日志轮转失败 + +```bash +# 诊断步骤 +cat /var/log/nginx/error.log | head # 查看是否有日志无法写入 +ls -la /var/log/nginx/ # 查看日志文件 +/usr/sbin/logrotate -d /etc/logrotate.d/nginx # 测试 logrotate +``` + +**修复方案**： +```bash +# 修改 /etc/logrotate.d/nginx 中的 postrotate 脚本 +# 将 invoke-rc.d nginx rotate 改为： +postrotate + systemctl reload nginx +endscript +``` + +--- + +## 三、数据库连接故障 + +### 3.1 MySQL 连接失败 + +```bash +# 诊断步骤 +mysql -h -P -u root -p # 测试连接 +telnet # 检查端口 +systemctl status mysql # 检查服务 +``` + +**常见原因**： +- 服务未运行 +- 防火墙未放行 3306 端口 +- 用户权限 / host 限制 +- 连接数超限 + +**解决方案**： +```bash +# 检查连接数 +mysql -e "SHOW VARIABLES LIKE 'max_connections';" +mysql -e "SHOW PROCESSLIST;" + +# 检查用户权限 +mysql -e "SELECT user, host FROM mysql.user WHERE user='root';" +``` + +### 3.2 MySQL 空间不足 + +```bash +# 诊断 +df -h # 磁盘空间 +mysql -e "SELECT table_schema, ROUND(SUM(data_length+index_length)/1024/1024,2) AS size_mb FROM information_schema.tables GROUP BY table_schema ORDER BY size_mb DESC;" +``` + +**解决方案**： +- 清理过期 binlog：`PURGE BINARY LOGS BEFORE DATE_SUB(NOW(), INTERVAL 7 DAY);` +- 清理临时表 +- 扩展磁盘 + +--- + +## 四、磁盘空间告警 + +### 4.1 诊断 + +```bash +df -h # 查看各分区使用率 +du -sh /* 2>/dev/null | sort -rh | head -10 # 找到大文件目录 +find / -type f -size +100M -exec ls -lh {} \; 2>/dev/null # 大文件定位 +``` + +### 4.2 清理方案 + +```bash +# Docker 日志和镜像清理 +docker system prune -af --volumes # 清理未使用的 Docker 资源 + +# 系统日志轮转 +journalctl --vacuum-time=7d # 清理 7 天前的 journal 日志 + +# 应用日志归档 +find /var/log -name "*.log" -mtime +30 -exec gzip {} \; # 压缩旧日志 +find /var/log -name "*.gz" -mtime +90 -delete # 删除 90 天前的压缩日志 +``` + +--- + +## 五、Docker 容器异常 + +### 5.1 容器停止 + +```bash +docker ps -a | grep # 查看容器状态 +docker logs --tail 50 # 查看最近日志 +``` + +**修复**： +```bash +docker start # 手动启动 +docker compose -f up -d # 使用 Compose 重启 +``` + +### 5.2 Docker API 无响应 + +```bash +systemctl status docker # 检查 Docker 服务 +journalctl -u docker --no-pager -n 50 # 查看 Docker 日志 +``` + +**修复**： +```bash +systemctl restart docker # 重启 Docker 守护进程 +``` + +--- + +## 六、系统进程故障 + +### 6.1 端口被占用 + +```bash +ss -tlnp | grep # 查看占用端口的进程 +fuser -k /tcp # 强制释放端口 +``` + +### 6.2 systemd 服务异常 + +```bash +systemctl status # 检查状态 +journalctl -u --no-pager -n 100 # 查看服务日志 + +# 常用修复 +systemctl daemon-reload # 重载 unit 文件 +systemctl restart # 重启 +systemctl enable # 设置开机自启 +``` + +--- + +## 七、日志分析工具 + +### 7.1 常用命令 + +```bash +# 实时日志跟踪 +tail -f /var/log//access.log + +# 错误过滤 +grep -i "error\|exception\|failed" /var/log//app.log | tail -50 + +# 时间范围过滤 +awk '/2026-06-24 10:00/,/2026-06-24 11:00/' /var/log//app.log +``` + +### 7.2 关键检查点 + +| 故障表现 | 优先检查 | 常见根因 | +|----------|----------|----------| +| 服务无响应 | systemctl status | 进程 OOM / 崩溃 | +| API 返回错误 | 应用日志 + Nginx 日志 | 代码 bug / 上游依赖异常 | +| 高延迟 | top + ss + 应用日志 | 资源争抢 / 死锁 | +| 数据库异常 | MySQL error log | 慢查询 / 连接数超限 | + +--- + +## 相关条目 + +- [部署流程_v1.0.md](部署流程_v1.0.md) +- [服务器运维标准_v1.0.md](服务器运维标准_v1.0.md) + +## 变更记录 + +| 日期 | 版本 | 变更说明 | 变更人 | +|------|------|----------|--------| +| 2026-06-24 | v1.0 | 初始创建 | 严维序 | \ No newline at end of file diff --git a/knowledge/运维/服务器运维标准_v1.0.md b/knowledge/运维/服务器运维标准_v1.0.md new file mode 100644 index 0000000..742b9d5 --- /dev/null +++ b/knowledge/运维/服务器运维标准_v1.0.md @@ -0,0 +1,177 @@ +# 服务器运维标准 + +## 元数据 + +| 属性 | 值 | +|------|-----| +| **领域** | 运维 | +| **责任人** | 严维序（opengineer） | +| **版本** | v1.0 | +| **创建日期** | 2026-06-24 | +| **最后更新** | 2026-06-24 | +| **标签** | 运维, 监控, 巡检, 备份 | + +## 概述 + +本文档定义 BizWings 团队所有服务器的日常运维标准，包括巡检频率、监控指标、备份策略和安全基线。适用于所有生产环境服务器（阿里云 / 家庭内网 / HP 服务器）。 + +--- + +## 一、服务器巡检标准 + +### 1.1 巡检频率 + +| 类型 | 频率 | 执行方式 | +|------|------|----------| +| 心跳自检 | 每 10 分钟 | openclaw 心跳自动巡检 | +| 深度巡检 | 每日一次 | 手动执行 `python3 $SCRIPTS/heartbeat_helper.py opengineer` | +| 全量巡检 | 每周一次 | 逐个检查全部服务器 | + +### 1.2 巡检清单 + +#### 资源负载 +```bash +# 磁盘使用率（警告 > 80%，严重 > 90%） +df -h | grep -v tmpfs + +# CPU 负载 +uptime + +# 内存使用 +free -h + +# 网络 IO +sar -n DEV 1 3 +``` + +#### 服务状态 +```bash +# 核心服务清单（按实际部署确认） +systemctl status nginx mysql docker sshd + +# Docker 容器健康 +docker ps | grep -c "Up" +``` + +#### 日志异常 +```bash +# 最近 10 分钟的错误日志 +journalctl --since "10 min ago" -p err --no-pager | tail -20 +``` + +--- + +## 二、监控指标定义 + +### 2.1 告警阈值 + +| 指标 | 警告 (WARN) | 严重 (CRIT) | 处理 | +|------|-------------|-------------|------| +| 磁盘使用率 | > 80% | > 90% | 清理日志 / 扩容 | +| CPU 负载 (1min) | > 4.0 | > 8.0 | 检查异常进程 | +| 内存使用率 | > 85% | > 95% | 检查 OOM 风险 | +| 根分区 inode | > 80% | > 90% | 清理小文件 | +| 服务进程 | 停止 | — | 重启服务 | +| 端口监听 | 消失 | — | 检查服务状态 | +| Docker 容器 | 非 Up | — | docker start / compose up | + +### 2.2 日志监控 + +- 系统日志：`journalctl -p err` 重点关注 +- 应用日志：`error`, `exception`, `failed`, `timeout` 关键词监控 +- Nginx 日志：5xx 错误率 > 1% 时触发调查 + +--- + +## 三、备份策略 + +### 3.1 数据库备份 + +```bash +# MySQL 全量备份（建议每日凌晨执行） +mysqldump --all-databases --single-transaction --quick | gzip > /backup/db/all-$(date +%Y%m%d).sql.gz +``` + +### 3.2 配置备份 +- 服务器配置文件：`/backup/conf//` 目录 +- 每次变更前执行：`cp .$(date +%Y%m%d-%H%M%S).bak` + +### 3.3 Docker 数据备份 +```bash +# 思源笔记备份（已配置每日 3:00） +tar czf /backup/siyuan/siyuan-data-$(date +%Y%m%d).tar.gz -C . +``` + +### 3.4 备份保留策略 + +| 类型 | 保留期限 | +|------|----------| +| 数据库全量备份 | 30 天 | +| 配置备份 | 90 天 | +| Docker 数据 | 7 天 | +| 日志归档 | 90 天 | + +--- + +## 四、变更管理标准 + +### 4.1 变更准入 + +- ✅ 每次变更前必须备份原始文件 +- ✅ 高危操作（防火墙、内核、数据库）必须保留回滚方案 +- ✅ 变更前评估影响范围 +- ✅ 变更后验证服务状态 +- ❌ 禁止在无备份的情况下直接修改生产配置 +- ❌ 禁止在高峰时段执行非紧急变更 + +### 4.2 变更分级 + +| 级别 | 示例 | 要求 | +|------|------|------| +| 低风险 | 普通应用更新 | 备份 → 部署 → 验证 | +| 中风险 | 配置修改 | 备份 → 预演 → 部署 → 验证 | +| 高风险 | 内核 / 防火墙 / 数据库 | 备份 → 预演 → 通知 → 部署 → 验证 → 监控 | + +--- + +## 五、安全基线 + +### 5.1 基本要求 + +- [ ] SSH 禁止 root 密码登录（高风险服务器） +- [ ] 防火墙最小权限原则 +- [ ] 非必要端口不对外开放 +- [ ] 定期更新系统安全补丁 +- [ ] 日志审计开启 + +### 5.2 密码管理 + +- 服务器密码统一记录在 TOOLS.md +- 数据库密码统一管理 +- 禁止在代码中硬编码密码 + +--- + +## 六、服务器清单与分类 + +| 环境 | 服务器数 | 用途 | 巡检频率 | +|------|----------|------|----------| +| 阿里云生产 | 3 | 应用服务、数据库 | 每次心跳 | +| 家庭内网生产 | 4 | 应用、数据库、PVE | 每次心跳 | +| HP 测试 | 3 | 测试、NAS | 每日 | +| 树莓派 | 1 | 辅助设备 | 每日 | + +详细清单见 TOOLS.md「SSH/WinRM 服务器清单」 + +--- + +## 相关条目 + +- [部署流程_v1.0.md](部署流程_v1.0.md) +- [故障排查手册_v1.0.md](故障排查手册_v1.0.md) + +## 变更记录 + +| 日期 | 版本 | 变更说明 | 变更人 | +|------|------|----------|--------| +| 2026-06-24 | v1.0 | 初始创建 | 严维序 | \ No newline at end of file diff --git a/knowledge/运维/部署流程_v1.0.md b/knowledge/运维/部署流程_v1.0.md new file mode 100644 index 0000000..944eecd --- /dev/null +++ b/knowledge/运维/部署流程_v1.0.md @@ -0,0 +1,202 @@ +# 服务部署流程 SOP + +## 元数据 + +| 属性 | 值 | +|------|-----| +| **领域** | 运维 | +| **责任人** | 严维序（opengineer） | +| **版本** | v1.0 | +| **创建日期** | 2026-06-24 | +| **最后更新** | 2026-06-24 | +| **标签** | 部署, 运维, SOP | + +## 概述 + +本文档定义 BizWings 团队所有业务服务的部署流程标准，涵盖部署前检查、执行步骤、验证测试和回滚预案。适用于所有生产环境的代码部署与服务更新。 + +--- + +## 一、部署前置检查 + +### 1.1 代码准备 + +- [ ] 代码已合并到目标分支（main / release） +- [ ] PR 已通过 Code Review 并合并 +- [ ] 本地或 CI 构建通过（编译无报错） +- [ ] 版本号已更新（如有） + +### 1.2 环境检查 + +- [ ] 目标服务器磁盘空间充足（> 剩余 20%） +- [ ] CPU / 内存负载正常（< 80%） +- [ ] 网络连通性：本机 → 目标服务器可达 +- [ ] 目标端口未被占用 +- [ ] 依赖服务（数据库 / 中间件）运行正常 + +### 1.3 备份准备 + +- [ ] **配置备份**：服务器配置文件备份到 `/backup/conf/` 目录 +- [ ] **数据库备份**：涉及数据库变更，先执行 `mysqldump` 全量备份 +- [ ] **当前版本标记**：记录当前运行版本号或 Git commit hash + +--- + +## 二、部署执行步骤 + +### 2.1 文件分发 + +```bash +# 标准部署（SSH + scp/rsync） +scp -P ./dist/app root@:/opt/app/ +# 或使用 rsync 增量同步 +rsync -avz --delete -e "ssh -p " ./dist/ root@:/opt/app/ +``` + +### 2.2 服务更新 + +#### 方式 A：systemd 服务 +```bash +# 1. 停止服务 +systemctl stop + +# 2. 备份旧版本（如有必要） +mv /opt/app/ /opt/app/.bak + +# 3. 放置新版本 +cp /tmp/ /opt/app/ +chmod +x /opt/app/ + +# 4. 重启服务 +systemctl start +systemctl status +``` + +#### 方式 B：Docker 容器 +```bash +# 1. 拉取新镜像 +docker pull /: + +# 2. 停止旧容器 +docker stop +docker rm + +# 3. 启动新容器 +docker run -d --name \ + --restart unless-stopped \ + -p : \ + /: +``` + +#### 方式 C：Nginx 反向代理更新 +```bash +# 更新上游配置后重载 +nginx -t # 语法检查 +systemctl reload nginx # 热重载 +``` + +### 2.3 配置变更 + +```bash +# 1. 备份当前配置 +cp /etc//config.yml /etc//config.yml.$(date +%Y%m%d-%H%M%S) + +# 2. 修改配置 +vim /etc//config.yml + +# 3. 重启服务使配置生效 +systemctl restart +``` + +--- + +## 三、部署验证 + +### 3.1 连通性验证 +```bash +# 服务端口监听确认 +ss -tlnp | grep + +# HTTP 服务健康检查 +curl -s -o /dev/null -w "%{http_code}" http://localhost:/health +# 预期返回：200 +``` + +### 3.2 功能验证 + +- [ ] API 基础功能运行正常 +- [ ] 日志无新增 ERROR 级别报错 +- [ ] 数据库连接正常 +- [ ] 前端页面（如有）可正常加载 + +### 3.3 监控确认 + +- [ ] Prometheus / Grafana 指标正常 +- [ ] 日志系统（如有）已捕获新日志 +- [ ] 告警规则未被触发 + +--- + +## 四、回滚方案 + +### 4.1 代码回滚 +```bash +# Git 回滚到上一版本 +cd /opt/app/repo +git revert HEAD --no-edit +git push +# 重新执行部署 +``` + +### 4.2 文件回滚 +```bash +# 恢复备份文件 +mv /opt/app/.bak /opt/app/ +systemctl restart +``` + +### 4.3 数据库回滚 +```bash +# 导入备份 +gunzip < /backup/db/.$(date +%Y%m%d).sql.gz | mysql -u root -p +``` + +### 4.4 回滚确认 +- [ ] 旧版本服务运行正常 +- [ ] 端口监听确认 +- [ ] 用户无访问异常 +- [ ] 记录回滚原因到工作日志 + +--- + +## 五、部署后记录 + +### 5.1 必填信息 + +| 项目 | 内容 | +|------|------| +| 部署时间 | YYYY-MM-DD HH:mm | +| 部署人 | 严维序（opengineer） | +| 部署内容 | [简要描述] | +| 版本 | commit hash / tag | +| 验证结果 | ✅/❌ 通过 | +| 回滚情况 | 无需回滚 / 已回滚（原因） | + +### 5.2 记录位置 + +- 工作日志：`memory/YYYY-MM-DD.md` +- 任务记录：WorkBoard 相关卡片注释 +- 知识更新：如部署暴露流程问题，更新本文档 + +--- + +## 相关条目 + +- [故障排查手册_v1.0.md](故障排查手册_v1.0.md) +- [服务器运维标准_v1.0.md](服务器运维标准_v1.0.md) + +## 变更记录 + +| 日期 | 版本 | 变更说明 | 变更人 | +|------|------|----------|--------| +| 2026-06-24 | v1.0 | 初始创建 | 严维序 | \ No newline at end of file