====== 🔧 DV IT Infrastructure Platform - 故障排查指南 ======

**更新日期**: 2025年1月  
**项目**: DV IT Infrastructure Platform  
**基于**: 生产环境实际故障排查经验  
**VPS**: 156.67.214.225

-----

===== 🎯 故障排查概述 =====

==== 排查原则 ====
  * **系统性排查**: 从网络→容器→服务→应用逐层排查
  * **日志优先**: 优先查看容器和服务日志
  * **配置验证**: 检查配置文件和环境变量
  * **网络隔离**: 验证Docker网络和Traefik路由

==== 常用命令 ====
<code bash>
# 查看所有容器状态
docker ps -a

# 查看容器日志
docker logs <container_name>

# 查看网络
docker network ls
docker network inspect <network_name>

# 查看Traefik路由
docker logs traefik

# 检查端口
netstat -tlnp | grep :80
netstat -tlnp | grep :443
</code>

-----

===== 🚨 常见故障及解决方案 =====

==== 1. 服务无法通过域名访问 ====

===== 症状 =====
  * 域名返回 404 或连接超时
  * 直接IP访问正常，域名访问异常

===== 排查步骤 =====

==== 1. 检查Traefik容器状态 ====
<code bash>
docker ps | grep traefik
docker logs traefik
</code>

==== 2. 检查Traefik labels配置 ====
<code bash>
# 检查容器是否配置了正确的labels
docker inspect <container_name> | grep -A 10 -B 5 "Labels"
</code>

==== 3. 检查网络连接 ====
<code bash>
# 检查容器是否在traefik-network中
docker network inspect traefik-network

# 检查容器间网络连通性
docker exec -it <container_name> ping traefik
</code>

==== 4. 检查SSL证书 ====
<code bash>
# 检查acme.json权限
ls -la /opt/discountvapor-it/traefik/acme.json

# 检查证书内容
docker exec traefik ls -la /letsencrypt/
</code>

===== 解决方案 =====

==== 问题1: 容器未加入traefik-network ====
<code bash>
# 将容器加入网络
docker network connect traefik-network <container_name>

# 重启容器
docker restart <container_name>
</code>

==== 问题2: Traefik labels配置错误 ====
<code yaml>
# 正确的labels配置示例
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.service.rule=Host(`domain.oasisvape.co.nz`)"
  - "traefik.http.routers.service.entrypoints=websecure"
  - "traefik.http.routers.service.tls.certresolver=letsencrypt"
  - "traefik.http.services.service.loadbalancer.server.port=<port>"
  - "traefik.docker.network=traefik-network"
</code>

==== 问题3: SSL证书权限问题 ====
<code bash>
# 修复acme.json权限
chmod 600 /opt/discountvapor-it/traefik/acme.json
chown 1000:1000 /opt/discountvapor-it/traefik/acme.json

# 重启Traefik
docker restart traefik
</code>

-----

==== 2. ERPNext 404/500 错误 ====

===== 症状 =====
  * ERPNext返回404或500错误
  * 数据库连接失败
  * 前端无法加载

===== 排查步骤 =====

==== 1. 检查ERPNext容器状态 ====
<code bash>
docker ps | grep erpnext
docker logs discountvapor-it-frontend-1
docker logs discountvapor-it-backend-1
</code>

==== 2. 检查数据库连接 ====
<code bash>
# 检查MariaDB容器
docker logs discountvapor-it-database-1

# 检查数据库连接
docker exec -it discountvapor-it-backend-1 bench doctor
</code>

==== 3. 检查Redis连接 ====
<code bash>
# 检查Redis容器
docker logs discountvapor-it-redis-cache-1
docker logs discountvapor-it-redis-queue-1
</code>

===== 解决方案 =====

==== 问题1: 数据库密码错误 ====
<code bash>
# 检查.env文件中的DB_PASSWORD
cat /opt/discountvapor-it/.env

# 重新配置数据库连接
docker exec -it discountvapor-it-configurator-1 bench set-config -g db_host database
docker exec -it discountvapor-it-configurator-1 bench set-config -gp db_port 3306
</code>

==== 问题2: 权限问题 ====
<code bash>
# 修复数据目录权限
chown -R 1000:1000 /opt/discountvapor-it/data/erpnext/

# 重启ERPNext服务
docker compose -f docker-compose-erpnext.yml restart
</code>

==== 问题3: 配置问题 ====
<code bash>
# 重新运行配置器
docker compose -f docker-compose-erpnext.yml up configurator

# 重启所有ERPNext服务
docker compose -f docker-compose-erpnext.yml restart
</code>

-----

==== 3. n8n 登录页面异常 ====

===== 症状 =====
  * n8n登录页面显示异常
  * 无法正常登录
  * Webhook URL配置错误

===== 排查步骤 =====

==== 1. 检查n8n配置 ====
<code bash>
docker logs discountvapor-it-n8n-1
docker inspect discountvapor-it-n8n-1 | grep -A 20 "Env"
</code>

==== 2. 检查N8N_HOST配置 ====
<code bash>
# 检查环境变量
docker exec -it discountvapor-it-n8n-1 env | grep N8N
</code>

===== 解决方案 =====

==== 问题1: N8N_HOST配置错误 ====
<code yaml>
# 正确的n8n配置
environment:
  - N8N_HOST=n8n.oasisvape.co.nz
  - N8N_PORT=5678
  - WEBHOOK_TUNNEL_URL=https://n8n.oasisvape.co.nz
</code>

==== 问题2: 数据库连接问题 ====
<code bash>
# 检查PostgreSQL连接
docker exec -it discountvapor-it-n8n-1 ping strapi_postgres

# 检查数据库schema
docker exec -it strapi_postgres psql -U strapi_user -d strapi_db -c "\dn"
</code>

-----

==== 4. DokuWiki 安装页面问题 ====

===== 症状 =====
  * DokuWiki显示安装页面
  * 主页面返回404
  * 权限问题

===== 排查步骤 =====

==== 1. 检查DokuWiki配置 ====
<code bash>
docker logs dokuwiki
docker exec -it dokuwiki ls -la /config/dokuwiki/
</code>

==== 2. 检查数据目录权限 ====
<code bash>
ls -la /opt/discountvapor-it/data/
chown -R 1000:1000 /opt/discountvapor-it/data/
</code>

===== 解决方案 =====

==== 问题1: 权限问题 ====
<code bash>
# 修复权限
chown -R 1000:1000 /opt/discountvapor-it/data/
chown -R 1000:1000 /opt/discountvapor-it/logs/

# 重启DokuWiki
docker restart dokuwiki
</code>

==== 问题2: 配置问题 ====
<code yaml>
# 正确的DokuWiki配置
environment:
  - PUID=1000
  - PGID=1000
  - TZ=Pacific/Auckland
volumes:
  - ./data:/config
  - ./logs:/var/log/dokuwiki
</code>

-----

==== 5. Grafana 访问问题 ====

===== 症状 =====
  * Grafana无法访问
  * 登录失败
  * 数据目录权限问题

===== 排查步骤 =====

==== 1. 检查Grafana容器 ====
<code bash>
docker logs grafana
docker exec -it grafana ls -la /var/lib/grafana/
</code>

==== 2. 检查数据目录权限 ====
<code bash>
ls -la /opt/discountvapor-it/data/grafana/
</code>

===== 解决方案 =====

==== 问题1: 权限问题 ====
<code bash>
# 修复Grafana数据目录权限
chown -R 472:472 /opt/discountvapor-it/data/grafana/

# 重启Grafana
docker restart grafana
</code>

==== 问题2: 配置问题 ====
<code yaml>
# 正确的Grafana配置
environment:
  - GF_SECURITY_ADMIN_USER=admin
  - GF_SECURITY_ADMIN_PASSWORD=35@Riccarton
  - GF_USERS_ALLOW_SIGN_UP=false
  - TZ=Pacific/Auckland
</code>

-----

==== 6. SSL证书问题 ====

===== 症状 =====
  * HTTPS访问失败
  * 证书过期
  * 证书申请失败

===== 排查步骤 =====

==== 1. 检查acme.json ====
<code bash>
ls -la /opt/discountvapor-it/traefik/acme.json
docker exec traefik ls -la /letsencrypt/
</code>

==== 2. 检查Traefik日志 ====
<code bash>
docker logs traefik | grep -i "certificate\|acme\|error"
</code>

==== 3. 检查域名解析 ====
<code bash>
nslookup erp.oasisvape.co.nz
nslookup cms.oasisvape.co.nz
</code>

===== 解决方案 =====

==== 问题1: acme.json权限问题 ====
<code bash>
# 修复权限
chmod 600 /opt/discountvapor-it/traefik/acme.json
chown 1000:1000 /opt/discountvapor-it/traefik/acme.json

# 重启Traefik
docker restart traefik
</code>

==== 问题2: 证书申请失败 ====
<code bash>
# 删除旧的acme.json（谨慎操作）
rm /opt/discountvapor-it/traefik/acme.json

# 重启Traefik重新申请证书
docker restart traefik
</code>

==== 问题3: 域名解析问题 ====
<code bash>
# 检查DNS记录
dig erp.oasisvape.co.nz
dig cms.oasisvape.co.nz

# 确保A记录指向正确的IP
# 156.67.214.225
</code>

-----

==== 7. 防火墙问题 ====

===== 症状 =====
  * 外部无法访问服务
  * 端口被阻止
  * 内部服务正常，外部访问失败

===== 排查步骤 =====

==== 1. 检查防火墙状态 ====
<code bash>
ufw status
iptables -L
</code>

==== 2. 检查端口监听 ====
<code bash>
netstat -tlnp | grep :80
netstat -tlnp | grep :443
</code>

===== 解决方案 =====

==== 问题1: 防火墙阻止端口 ====
<code bash>
# 开放必要端口
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp

# 关闭其他端口
ufw deny 3000
ufw deny 5678
ufw deny 8080
ufw deny 8081
ufw deny 8180
ufw deny 9090
</code>

==== 问题2: 端口未监听 ====
<code bash>
# 检查Traefik是否监听80/443端口
docker logs traefik

# 重启Traefik
docker restart traefik
</code>

-----

===== 🔍 系统级故障排查 =====

==== 1. 磁盘空间不足 ====

==== 检查命令 ====
<code bash>
# 检查磁盘使用情况
df -h

# 检查Docker使用情况
docker system df

# 检查大文件
du -sh /opt/discountvapor-it/data/* | sort -hr
</code>

==== 解决方案 ====
<code bash>
# 清理Docker缓存
docker system prune -a

# 清理日志文件
find /opt/discountvapor-it/logs/ -name "*.log" -mtime +7 -delete

# 清理备份文件
find /opt/discountvapor-it/config_backup/ -name "*.bak" -mtime +30 -delete
</code>

==== 2. 内存不足 ====

==== 检查命令 ====
<code bash>
# 检查内存使用
free -h

# 检查容器内存使用
docker stats --no-stream
</code>

==== 解决方案 ====
<code bash>
# 重启内存占用高的容器
docker restart <container_name>

# 调整容器内存限制
# 在docker-compose.yml中添加
# deploy:
#   resources:
#     limits:
#       memory: 1G
</code>

==== 3. 网络问题 ====

==== 检查命令 ====
<code bash>
# 检查网络接口
ip addr show

# 检查路由
ip route show

# 检查DNS
cat /etc/resolv.conf
</code>

==== 解决方案 ====
<code bash>
# 重启网络服务
systemctl restart networking

# 重启Docker网络
docker network prune
docker network create traefik-network
</code>

-----

===== 📊 监控和告警 =====

==== 1. 设置监控告警 ====

==== Grafana告警配置 ====
<code yaml>
# 在Grafana中配置告警规则
- alert: ContainerDown
  expr: up == 0
  for: 1m
  labels:
    severity: critical
  annotations:
    summary: "Container {{ $labels.instance }} is down"
</code>

==== 系统监控 ====
<code bash>
# 设置系统监控脚本
#!/bin/bash
# 检查容器状态
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -v "Up"

# 检查磁盘空间
df -h | awk '$5 > "80%" {print $0}'

# 检查内存使用
free -h | awk 'NR==2{if($3/$2 > 0.8) print "Memory usage high: " $3 "/" $2}'
</code>

==== 2. 日志监控 ====

==== 日志轮转配置 ====
<code bash>
# 配置logrotate
cat > /etc/logrotate.d/docker-logs << EOF
/opt/discountvapor-it/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 644 root root
}
EOF
</code>

-----

===== 🔄 恢复和备份 =====

==== 1. 服务恢复流程 ====
<code bash>
# 1. 停止所有服务
docker compose -f docker-compose-*.yml down

# 2. 备份当前状态
tar -czf backup-$(date +%Y%m%d_%H%M%S).tar.gz /opt/discountvapor-it/

# 3. 恢复配置
cp config_backup/*.yml ./
cp config_backup/.env ./

# 4. 重启服务
docker compose -f docker-compose-traefik.yml up -d
docker compose -f docker-compose-erpnext.yml up -d
docker compose -f docker-compose-strapi.yml up -d
docker compose -f docker-compose-n8n.yml up -d
docker compose -f docker-compose-dokuwiki.yml up -d
docker compose up -d
</code>

==== 2. 数据库恢复 ====
<code bash>
# ERPNext数据库恢复
docker exec -i discountvapor-it-database-1 mysql -u root -p${DB_PASSWORD} < backup.sql

# PostgreSQL数据库恢复
docker exec -i strapi_postgres psql -U strapi_user -d strapi_db < backup.sql
</code>

-----

===== 📞 紧急联系 =====

==== 技术支持 ====
  * **项目文档**: https://wiki.oasisvape.co.nz
  * **监控面板**: https://grafana.oasisvape.co.nz
  * **联系邮箱**: discountvapor2025@gmail.com

==== 服务商支持 ====
  * **VPS提供商**: Hostinger
  * **域名管理**: Cloudflare
  * **SSL证书**: Let's Encrypt

-----

===== 📋 故障排查检查清单 =====

==== 服务状态检查 ====
  * [ ] 所有容器运行正常
  * [ ] 网络连接正常
  * [ ] 数据库连接正常
  * [ ] SSL证书有效
  * [ ] 防火墙配置正确

==== 日志检查 ====
  * [ ] Traefik日志无错误
  * [ ] 应用日志无错误
  * [ ] 系统日志无错误
  * [ ] 数据库日志正常

==== 配置检查 ====
  * [ ] 环境变量正确
  * [ ] Docker Compose配置正确
  * [ ] Traefik labels配置正确
  * [ ] 网络配置正确

==== 性能检查 ====
  * [ ] 磁盘空间充足
  * [ ] 内存使用正常
  * [ ] CPU使用正常
  * [ ] 网络带宽充足

-----

**最后更新**: 2025-01-06  
**基于生产环境**: 156.67.214.225