# 故障排查

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [src/main.rs](file://src/main.rs)
- [src/cli.rs](file://src/cli.rs)
- [src/error.rs](file://src/error.rs)
- [src/state.rs](file://src/state.rs)
- [src/config.rs](file://src/config.rs)
- [src/discovery.rs](file://src/discovery.rs)
- [src/container.rs](file://src/container.rs)
- [src/nginx.rs](file://src/nginx.rs)
- [src/compose.rs](file://src/compose.rs)
- [src/network.rs](file://src/network.rs)
- [src/micro_app_config.rs](file://src/micro_app_config.rs)
- [src/volumes_config.rs](file://src/volumes_config.rs)
- [Cargo.toml](file://Cargo.toml)
</cite>

## 目录
1. [简介](#简介)
2. [问题分类索引](#问题分类索引)
3. [日志分析方法](#日志分析方法)
4. [端口冲突问题](#端口冲突问题)
5. [容器启动失败](#容器启动失败)
6. [网络连接问题](#网络连接问题)
7. [状态文件问题](#状态文件问题)
8. [Docker 相关问题](#docker-相关问题)
9. [Nginx 配置问题](#nginx-配置问题)
10. [SSL 证书问题](#ssl-证书问题)
11. [性能问题](#性能问题)
12. [配置错误模式](#配置错误模式)
13. [问题上报指南](#问题上报指南)
14. [结论](#结论)

## 简介

micro_proxy 是一个用于管理微应用的工具，支持 Docker 镜像构建、容器管理、Nginx 反向代理配置等功能。本文档提供了系统性的故障排查指南，涵盖从基础的日志分析到复杂的系统集成问题。

## 问题分类索引

根据问题的性质和影响范围，我们将故障分为以下类别：

### 1. 配置类问题
- 配置文件格式错误
- 配置项缺失或无效
- 应用配置冲突

### 2. 系统环境问题
- 端口冲突
- 权限不足
- 磁盘空间不足

### 3. Docker 容器问题
- 容器启动失败
- 网络连接异常
- 卷挂载问题

### 4. Nginx 代理问题
- 配置生成错误
- 反向代理失效
- SSL 证书问题

### 5. 应用发现问题
- 微应用扫描失败
- 配置文件缺失
- 应用名称冲突

## 日志分析方法

### 1. 启用详细日志
```bash
# 使用 -v 或 --verbose 参数获取详细日志
micro_proxy start -v
micro_proxy status -v
```

### 2. 日志文件位置
- 日志文件名与包名称一致：`micro_proxy.log`
- 日志同时输出到控制台和文件

### 3. 关键日志信息提取

#### 配置加载阶段
```bash
# 配置文件加载成功
INFO: 配置文件加载成功
DEBUG: 配置内容: { ... }

# 应用发现阶段
INFO: 开始扫描微应用目录...
INFO: 发现有效微应用：{name} (容器：{container})
```

#### 容器管理阶段
```bash
# 容器操作日志
INFO: 创建容器: {container_name}
INFO: 容器创建成功: {container_name}
INFO: 容器启动成功: {container_name}
```

#### Nginx 配置阶段
```bash
# Nginx 配置生成
INFO: 开始生成nginx配置
INFO: 检测到SSL证书，启用HTTPS配置
INFO: nginx配置生成完成
```

**章节来源**
- [src/cli.rs:78-116](file://src/cli.rs#L78-L116)
- [src/main.rs:6-24](file://src/main.rs#L6-L24)

## 端口冲突问题

### 1. 问题识别
- 宿主机端口被其他进程占用
- Docker 端口映射冲突
- 防火墙阻止端口访问

### 2. 诊断步骤

#### 检查端口占用
```bash
# 检查特定端口占用情况
sudo lsof -i :80
sudo lsof -i :8080
sudo netstat -tulpn | grep :80
```

#### 验证 Nginx 配置
```bash
# 检查 Nginx 配置语法
docker exec proxy-nginx nginx -t
```

#### 查看容器端口映射
```bash
# 查看容器端口映射
docker port proxy-nginx
docker ps -l
```

### 3. 解决方案

#### 修改配置文件
```yaml
# 修改 proxy-config.yml 中的 nginx_host_port
nginx_host_port: 8080  # 改为其他未被占用的端口
```

#### 清理占用进程
```bash
# 查找占用端口的进程
sudo lsof -i :80
# 终止占用进程
sudo kill -9 PID
```

**章节来源**
- [README.md:363-372](file://README.md#L363-L372)
- [src/nginx.rs:26-92](file://src/nginx.rs#L26-L92)

## 容器启动失败

### 1. 常见原因
- Docker 镜像构建失败
- 容器启动参数错误
- 网络连接问题
- 权限不足

### 2. 诊断流程

#### 检查容器状态
```bash
# 查看所有容器状态
micro_proxy status
docker ps -a

# 检查特定容器状态
docker ps -l
```

#### 查看容器日志
```bash
# 查看容器日志
docker logs {container_name}
docker logs proxy-nginx

# 实时查看日志
docker logs -f {container_name}
```

#### 检查镜像状态
```bash
# 检查镜像是否存在
docker images | grep {app_name}
```

### 3. 排查步骤

#### 验证 Docker 环境
```bash
# 检查 Docker 服务状态
systemctl status docker

# 检查 Docker 版本
docker --version

# 检查 Docker 配额
docker info
```

#### 检查磁盘空间
```bash
# 检查磁盘空间
df -h

# 检查 Docker 占用空间
docker system df
```

#### 验证网络连接
```bash
# 检查网络连接
ping registry-1.docker.io
curl -I https://registry-1.docker.io
```

**章节来源**
- [src/container.rs:178-242](file://src/container.rs#L178-L242)
- [src/cli.rs:550-584](file://src/cli.rs#L550-L584)

## 网络连接问题

### 1. 问题表现
- 应用间通信失败
- Nginx 无法访问后端服务
- DNS 解析超时

### 2. 诊断方法

#### 生成网络地址列表
```bash
# 生成网络地址列表
micro_proxy network
cat network-addresses.txt
```

#### 检查 Docker 网络
```bash
# 查看网络状态
docker network ls
docker network inspect {network_name}

# 检查网络连接
docker network connect {network_name} {container_name}
```

#### 验证服务可达性
```bash
# 在 Nginx 容器内测试连接
docker exec proxy-nginx curl -I http://{service_name}:{port}

# 检查 DNS 解析
docker exec proxy-nginx nslookup {service_name}
```

### 3. 解决方案

#### 重新创建网络
```bash
# 删除现有网络
docker network rm {network_name}

# 重新创建网络
docker network create {network_name}
```

#### 检查防火墙设置
```bash
# 检查防火墙规则
sudo iptables -L

# 临时关闭防火墙测试
sudo systemctl stop firewalld
```

**章节来源**
- [src/network.rs:8-119](file://src/network.rs#L8-L119)
- [src/network.rs:209-274](file://src/network.rs#L209-L274)

## 状态文件问题

### 1. 状态文件的作用
状态文件用于跟踪微应用的构建状态，避免不必要的重复构建。

### 2. 状态文件结构
```yaml
# 状态文件示例结构
app_name:
  app_name: "app-name"
  hash: "a1b2c3d4e5f6..."
  last_built: 2024-01-01T00:00:00Z
  image_exists: true
```

### 3. 诊断步骤

#### 检查状态文件
```bash
# 查看状态文件内容
cat proxy-config.state

# 检查状态文件权限
ls -la proxy-config.state
```

#### 验证状态文件完整性
```bash
# 检查 YAML 格式
cat proxy-config.state | yamlfmt

# 重新生成状态文件
micro_proxy clean --force
micro_proxy start
```

### 4. 常见问题解决

#### 状态文件损坏
```bash
# 删除损坏的状态文件
rm proxy-config.state

# 重新构建应用
micro_proxy start --force-rebuild
```

#### 目录哈希计算问题
```bash
# 检查目录权限
ls -la {app_directory}

# 验证文件完整性
find {app_directory} -type f -exec md5sum {} \;
```

**章节来源**
- [src/state.rs:13-186](file://src/state.rs#L13-L186)
- [src/state.rs:188-233](file://src/state.rs#L188-L233)

## Docker 相关问题

### 1. Docker 服务问题

#### 检查 Docker 服务状态
```bash
# Linux 系统
systemctl status docker
sudo systemctl restart docker

# macOS 系统
brew services list | grep docker
```

#### 验证 Docker 权限
```bash
# 添加用户到 docker 组
sudo usermod -aG docker $USER

# 重新登录或执行
newgrp docker
```

### 2. 镜像构建问题

#### 检查 Dockerfile
```bash
# 验证 Dockerfile 语法
docker build --no-cache -t test-image .

# 检查 EXPOSE 指令
grep EXPOSE Dockerfile
```

#### 查看构建日志
```bash
# 查看构建历史
docker history {image_name}

# 检查构建缓存
docker builder prune
```

### 3. 卷挂载问题

#### 检查卷挂载
```bash
# 查看卷挂载详情
docker inspect {container_name} | grep -A 10 Mounts

# 检查卷权限
ls -la {host_path}
```

#### 重新挂载卷
```bash
# 停止容器
docker stop {container_name}

# 删除容器
docker rm {container_name}

# 重新启动
docker-compose up -d
```

**章节来源**
- [src/compose.rs:268-424](file://src/compose.rs#L268-L424)
- [src/discovery.rs:40-145](file://src/discovery.rs#L40-L145)

## Nginx 配置问题

### 1. 配置生成错误

#### 检查配置文件
```bash
# 验证 Nginx 配置语法
docker exec proxy-nginx nginx -t

# 查看配置文件内容
docker exec proxy-nginx cat /etc/nginx/nginx.conf
```

#### 常见配置错误

##### 路由配置问题
```nginx
# 错误：重复的 location 配置
location / {
    proxy_pass http://service1:8080;
}
location / {
    proxy_pass http://service2:8080;  # 覆盖前面的配置
}

# 正确：明确的路由映射
location /api {
    proxy_pass http://api-service:3000;
}
location / {
    proxy_pass http://frontend:80;
}
```

##### SSL 配置问题
```nginx
# 错误：证书路径错误
ssl_certificate /etc/nginx/certs/domain.crt;
ssl_certificate_key /etc/nginx/certs/domain.key;

# 正确：检查证书文件
docker exec proxy-nginx ls -la /etc/nginx/certs/
```

### 2. 反向代理失效

#### 检查上游服务
```bash
# 在 Nginx 容器内测试连接
docker exec proxy-nginx curl -I http://app-container:8080

# 检查服务健康状态
docker ps -l
```

#### 验证 DNS 解析
```bash
# 检查容器网络
docker exec proxy-nginx nslookup app-container

# 检查 Docker DNS
docker exec proxy-nginx cat /etc/resolv.conf
```

### 3. 配置修复步骤

#### 重新生成配置
```bash
# 重新生成 Nginx 配置
micro_proxy start

# 或者手动生成
docker exec proxy-nginx nginx -s reload
```

#### 检查权限设置
```bash
# 检查文件权限
docker exec proxy-nginx ls -la /etc/nginx/nginx.conf
docker exec proxy-nginx ls -la /var/www/html

# 修复权限
docker exec proxy-nginx chmod 644 /etc/nginx/nginx.conf
```

**章节来源**
- [src/nginx.rs:10-92](file://src/nginx.rs#L10-L92)
- [src/nginx.rs:272-536](file://src/nginx.rs#L272-L536)

## SSL 证书问题

### 1. 证书文件检查

#### 验证证书存在性
```bash
# 检查证书文件
ls -la /etc/nginx/certs/

# 检查证书内容
openssl x509 -in /etc/nginx/certs/example.com.crt -text -noout
openssl rsa -in /etc/nginx/certs/example.com.key -check
```

#### 验证证书有效性
```bash
# 检查证书有效期
openssl x509 -in /etc/nginx/certs/example.com.crt -dates -noout

# 检查证书链
openssl verify -CAfile /etc/nginx/certs/example.com.crt /etc/nginx/certs/example.com.crt
```

### 2. Let's Encrypt 配置

#### ACME 验证文件
```bash
# 检查 ACME 验证文件
ls -la /var/www/html/.well-known/acme-challenge/

# 验证文件权限
docker exec proxy-nginx ls -la /var/www/html/.well-known/acme-challenge/
```

#### 证书申请流程
```bash
# 使用 acme.sh 申请证书
acme.sh --issue -d example.com --webroot /var/www/html

# 部署证书
acme.sh --install-cert -d example.com \
  --key-file /etc/nginx/certs/example.com.key \
  --fullchain-file /etc/nginx/certs/example.com.crt
```

### 3. 常见 SSL 问题

#### 证书过期
```bash
# 重新申请证书
acme.sh --renew -d example.com

# 或者手动更新
acme.sh --renew-all
```

#### 证书链不完整
```bash
# 下载完整证书链
wget https://example.com/chain.pem
cat chain.pem >> /etc/nginx/certs/example.com.crt
```

#### 权限问题
```bash
# 修复证书权限
chmod 644 /etc/nginx/certs/example.com.crt
chmod 600 /etc/nginx/certs/example.com.key
chown root:root /etc/nginx/certs/example.com.*
```

**章节来源**
- [README.md:387-401](file://README.md#L387-L401)
- [src/nginx.rs:94-131](file://src/nginx.rs#L94-L131)

## 性能问题

### 1. 性能监控

#### 容器资源使用
```bash
# 查看容器资源使用
docker stats --no-stream

# 查看系统资源
top
htop
iotop
```

#### Nginx 性能指标
```bash
# 查看 Nginx 状态
docker exec proxy-nginx curl http://localhost/nginx_status

# 检查访问日志
docker exec proxy-nginx tail -f /var/log/nginx/access.log
```

### 2. 优化建议

#### Docker 配置优化
```yaml
# 在 docker-compose.yml 中添加优化配置
services:
  nginx:
    # 增加内存限制
    mem_limit: 512m
    # 设置 CPU 份额
    cpus: 0.5
    # 启用缓存优化
    volumes:
      - type: tmpfs
        target: /var/cache/nginx
        tmpfs:
          size: 104857600  # 100MB
```

#### Nginx 配置优化
```nginx
# 启用 gzip 压缩
gzip on;
gzip_types text/plain application/javascript application/json text/xml;

# 设置连接超时
proxy_connect_timeout 30s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;

# 启用 keep-alive
keepalive_timeout 65;
```

#### 应用优化
```yaml
# 在 micro-app.yml 中优化
nginx_extra_config: |
  # 启用缓存
  expires 1y;
  add_header Cache-Control "public, immutable";
  
  # 启用压缩
  gzip on;
  gzip_types text/plain application/javascript application/json;
```

**章节来源**
- [src/nginx.rs:486-536](file://src/nginx.rs#L486-L536)
- [src/compose.rs:358-424](file://src/compose.rs#L358-L424)

## 配置错误模式

### 1. 常见配置错误

#### 配置文件格式错误
```yaml
# 错误：缩进不正确
apps:
- name: app1
routes:  # 缺少缩进
  - /

# 正确：正确的缩进
apps:
  - name: app1
    routes:
      - /
```

#### 应用类型配置错误
```yaml
# 错误：类型不正确
app_type: web-server  # 无效类型

# 正确：允许的类型
app_type: static
app_type: api
app_type: internal
```

#### 端口配置错误
```yaml
# 错误：端口为 0
container_port: 0

# 错误：端口超出范围
container_port: 65536

# 正确：有效端口范围
container_port: 8080
```

### 2. 配置验证

#### 使用内置验证
```bash
# 启动时自动验证配置
micro_proxy start

# 手动验证配置
micro_proxy status
```

#### 配置文件检查清单
```bash
# 检查必需文件
ls -la proxy-config.yml
ls -la micro-app.yml

# 验证 YAML 格式
python3 -m yaml proxy-config.yml
python3 -m yaml micro-app.yml
```

### 3. 配置修复步骤

#### 逐步验证
```bash
# 1. 验证主配置文件
micro_proxy start -c proxy-config.yml

# 2. 验证单个应用配置
cat micro-apps/{app_name}/micro-app.yml

# 3. 检查 Dockerfile
cat micro-apps/{app_name}/Dockerfile
```

#### 重置配置
```bash
# 清理配置并重新生成
micro_proxy clean --force
micro_proxy start

# 或者手动重置
rm apps-config.yml
rm proxy-config.state
micro_proxy start
```

**章节来源**
- [src/config.rs:220-347](file://src/config.rs#L220-L347)
- [src/micro_app_config.rs:55-106](file://src/micro_app_config.rs#L55-L106)

## 问题上报指南

### 1. 收集必要信息

#### 系统信息
```bash
# 系统版本
uname -a
cat /etc/os-release

# Docker 版本
docker --version
docker info

# Rust 版本
rustc --version
cargo --version
```

#### 应用信息
```bash
# micro_proxy 版本
micro_proxy --version

# 配置文件内容
cat proxy-config.yml
cat apps-config.yml

# 状态文件
cat proxy-config.state
```

#### 日志信息
```bash
# 详细日志
micro_proxy start -v

# 查看最近的日志
tail -n 100 micro_proxy.log
```

### 2. 问题分类

#### Bug 报告模板
```markdown
## Bug 报告

### 环境信息
- micro_proxy 版本: 
- Docker 版本: 
- 系统版本: 
- Rust 版本: 

### 重现步骤
1. 
2. 
3. 

### 预期行为
- 

### 实际行为
- 

### 日志内容
```
[粘贴相关日志]
```

### 配置文件
```
[粘贴相关配置]
```
```

#### 功能请求模板
```markdown
## 功能请求

### 描述需求
- 

### 使用场景
- 

### 期望的解决方案
- 

### 替代方案
- 
```

### 3. 提交渠道

#### GitHub Issues
- 项目仓库：https://github.com/cao5zy/proxy-config
- 选择合适的标签：bug、enhancement、question
- 提供完整的环境信息和复现步骤

#### 社区支持
- 微信公众号：关注项目官方账号
- 项目文档：README.md 中的贡献部分

**章节来源**
- [README.md:454-460](file://README.md#L454-L460)

## 结论

本文档提供了 micro_proxy 的系统性故障排查指南，涵盖了从基础的日志分析到复杂的系统集成问题。通过遵循这些步骤，用户可以有效地诊断和解决大多数常见问题。

### 关键要点回顾

1. **日志分析**：始终使用 `-v` 参数获取详细日志，重点关注配置加载、容器管理和 Nginx 配置阶段的日志信息。

2. **分层诊断**：按照配置、Docker、网络、Nginx 的层次顺序进行诊断，避免跳跃式排查。

3. **预防措施**：定期检查系统资源、清理不必要的镜像和容器、备份重要配置文件。

4. **社区支持**：遇到复杂问题时，及时收集完整的环境信息和日志，通过 GitHub Issues 或社区渠道寻求帮助。

通过系统化的故障排查流程，大多数 micro_proxy 相关问题都可以得到快速有效的解决。建议用户在日常使用中建立定期维护和检查的习惯，以预防问题的发生。