feat(knowledge): opengineer - 创建运维/规范领域知识条目(部署流程/故障排查/服务器运维标准)

Co-authored-by: multica-agent <github@multica.ai>
2026-06-24 12:14:31 +08:00
parent bea11d04fb
commit 77f4eb1579
7 changed files with 710 additions and 1 deletions
@@ -0,0 +1,274 @@
+# 故障排查手册
+
+## 元数据
+
+| 属性 | 值 |
+|------|-----|
+| **领域** | 运维 |
+| **责任人** | 严维序（opengineer） |
+| **版本** | v1.0 |
+| **创建日期** | 2026-06-24 |
+| **最后更新** | 2026-06-24 |
+| **标签** | 故障排查, 运维, 排障 |
+
+## 概述
+
+本手册汇总 BizWings 环境中常见的系统与服务故障定位方法和修复方案。覆盖 SSH 连接、Nginx、数据库、磁盘、Docker 等核心场景。
+
+---
+
+## 一、SSH 连接故障
+
+### 1.1 连接超时
+
+```bash
+# 诊断步骤
+ssh -vvv root@<ip> -p <port>    # 查看详细连接日志
+ping <ip>                        # 检查网络连通性
+nmap <ip> -p <port>              # 检查端口状态
+```
+
+**常见原因**：
+- 目标服务器防火墙未开放端口
+- 源 IP 未加入白名单
+- 服务器负载过高，sshd 响应慢
+
+**解决方案**：
+1. 检查服务器防火墙：`iptables -L -n` 或 `ufw status`
+2. 检查 sshd 是否运行：`systemctl status sshd`
+3. 检查负载：`top -n1 | head -5`
+
+### 1.2 认证失败
+
+```bash
+# 诊断步骤
+ssh -p <port> root@<ip>          # 尝试密码登录
+# 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:<upstream-port>    # 检查上游服务
+ss -tlnp | grep <upstream-port>             # 检查端口监听
+systemctl status <upstream-service>         # 检查上游进程
+```
+
+**常见原因**：
+- 上游服务未启动或崩溃
+- 连接池耗尽
+
+**解决方案**：
+1. 重启上游服务：`systemctl restart <service>`
+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 <host> -P <port> -u root -p      # 测试连接
+telnet <host> <port>                       # 检查端口
+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 <container>         # 查看容器状态
+docker logs <container> --tail 50       # 查看最近日志
+```
+
+**修复**：
+```bash
+docker start <container>                # 手动启动
+docker compose -f <path> 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 <port>                  # 查看占用端口的进程
+fuser -k <port>/tcp                     # 强制释放端口
+```
+
+### 6.2 systemd 服务异常
+
+```bash
+systemctl status <service>              # 检查状态
+journalctl -u <service> --no-pager -n 100   # 查看服务日志
+
+# 常用修复
+systemctl daemon-reload                 # 重载 unit 文件
+systemctl restart <service>             # 重启
+systemctl enable <service>              # 设置开机自启
+```
+
+---
+
+## 七、日志分析工具
+
+### 7.1 常用命令
+
+```bash
+# 实时日志跟踪
+tail -f /var/log/<app>/access.log
+
+# 错误过滤
+grep -i "error\|exception\|failed" /var/log/<app>/app.log | tail -50
+
+# 时间范围过滤
+awk '/2026-06-24 10:00/,/2026-06-24 11:00/' /var/log/<app>/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 | 初始创建 | 严维序 |