# 开发调试流程

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [Cargo.toml](file://Cargo.toml)
- [src/main.rs](file://src/main.rs)
- [src/lib.rs](file://src/lib.rs)
- [src/cli.rs](file://src/cli.rs)
- [src/config.rs](file://src/config.rs)
- [src/discovery.rs](file://src/discovery.rs)
- [src/state.rs](file://src/state.rs)
- [src/builder.rs](file://src/builder.rs)
- [src/compose.rs](file://src/compose.rs)
- [src/nginx.rs](file://src/nginx.rs)
- [src/network.rs](file://src/network.rs)
- [src/volumes_config.rs](file://src/volumes_config.rs)
- [proxy-config.yml.example](file://proxy-config.yml.example)
- [docs/micro-app-development.md](file://docs/micro-app-development.md)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言

micro_proxy 是一个专为微应用开发而设计的管理工具，支持 Docker 镜像构建、容器管理、Nginx 反向代理配置等功能。本文档将为开发者提供从开发到部署的完整工作流程指南，涵盖开发环境搭建、配置管理、构建缓存、日志查看、问题排查以及开发效率提升的最佳实践。

## 项目结构

该项目采用 Rust 语言开发，遵循标准的 Cargo 项目结构：

```mermaid
graph TB
subgraph "项目根目录"
A[Cargo.toml] --> B[src/]
A --> C[docs/]
A --> D[assets/]
E[README.md] --> F[proxy-config.yml.example]
E --> G[micro-app.yml.example]
end
subgraph "src/ 源码目录"
B1[main.rs] --> B2[lib.rs]
B2 --> B3[cli.rs]
B2 --> B4[config.rs]
B2 --> B5[discovery.rs]
B2 --> B6[state.rs]
B2 --> B7[builder.rs]
B2 --> B8[compose.rs]
B2 --> B9[nginx.rs]
B2 --> B10[network.rs]
B2 --> B11[volumes_config.rs]
end
subgraph "docs/ 文档目录"
C1[micro-app-development.md]
C2[ssl-configuration.md]
C3[micro-app-volumes-refactor-plan.md]
end
```

**图表来源**
- [Cargo.toml:1-55](file://Cargo.toml#L1-L55)
- [src/lib.rs:1-26](file://src/lib.rs#L1-L26)

**章节来源**
- [Cargo.toml:1-55](file://Cargo.toml#L1-L55)
- [README.md:421-441](file://README.md#L421-L441)

## 核心组件

micro_proxy 的核心功能由以下主要组件构成：

### 命令行接口 (CLI)
负责处理用户输入和提供命令行交互界面，支持 start、stop、clean、status、network 等子命令。

### 配置管理系统
管理主配置文件和应用配置，支持 YAML 格式的配置解析和序列化。

### 应用发现模块
扫描指定目录，自动发现包含 micro-app.yml 和 Dockerfile 的微应用。

### 状态管理器
跟踪微应用的构建状态，实现智能的增量构建和缓存管理。

### 构建器模块
负责 Docker 镜像的构建过程，支持环境变量传递和缓存控制。

### Compose 生成器
自动生成 docker-compose.yml 文件，配置服务间的网络和依赖关系。

### Nginx 配置生成器
根据应用配置生成 Nginx 反向代理配置，支持静态资源和 API 服务的不同路由规则。

### 网络管理器
管理 Docker 网络的创建、删除和查询操作。

**章节来源**
- [src/cli.rs:1-669](file://src/cli.rs#L1-L669)
- [src/config.rs:1-842](file://src/config.rs#L1-L842)
- [src/discovery.rs:1-721](file://src/discovery.rs#L1-L721)
- [src/state.rs:1-311](file://src/state.rs#L1-L311)
- [src/builder.rs:1-218](file://src/builder.rs#L1-L218)
- [src/compose.rs:1-905](file://src/compose.rs#L1-L905)
- [src/nginx.rs:1-1101](file://src/nginx.rs#L1-L1101)
- [src/network.rs:1-397](file://src/network.rs#L1-L397)

## 架构概览

micro_proxy 采用模块化的架构设计，各个组件职责明确，通过清晰的接口进行交互：

```mermaid
graph TB
subgraph "用户层"
CLI[命令行界面]
Config[配置文件]
end
subgraph "核心管理层"
Discovery[应用发现]
StateMgr[状态管理]
Builder[镜像构建]
ComposeGen[Compose生成]
NginxGen[Nginx配置生成]
NetworkMgr[网络管理]
end
subgraph "基础设施层"
Docker[Docker引擎]
FileSystem[文件系统]
Network[Docker网络]
end
CLI --> Discovery
CLI --> StateMgr
CLI --> Builder
CLI --> ComposeGen
CLI --> NginxGen
CLI --> NetworkMgr
Discovery --> FileSystem
StateMgr --> FileSystem
Builder --> Docker
ComposeGen --> FileSystem
NginxGen --> FileSystem
NetworkMgr --> Network
ComposeGen --> Docker
NginxGen --> Docker
```

**图表来源**
- [src/main.rs:1-25](file://src/main.rs#L1-L25)
- [src/cli.rs:78-116](file://src/cli.rs#L78-L116)
- [src/discovery.rs:235-352](file://src/discovery.rs#L235-L352)

## 详细组件分析

### 命令行接口组件

CLI 模块提供了完整的命令行交互功能，支持多种操作模式：

```mermaid
classDiagram
class Cli {
+PathBuf config
+bool verbose
+Commands command
+run(args) Result
}
class Commands {
<<enumeration>>
Start
Stop
Clean
Status
Network
}
class StartOptions {
+bool force_rebuild
}
class CleanOptions {
+bool force
+bool network
}
Cli --> Commands
Commands --> StartOptions
Commands --> CleanOptions
```

**图表来源**
- [src/cli.rs:22-69](file://src/cli.rs#L22-L69)

#### 命令执行流程

```mermaid
sequenceDiagram
participant User as 用户
participant CLI as CLI模块
participant Config as 配置管理
participant Discovery as 应用发现
participant State as 状态管理
participant Builder as 构建器
participant Compose as Compose生成
participant Nginx as Nginx生成
participant Docker as Docker引擎
User->>CLI : 执行命令
CLI->>Config : 加载配置
CLI->>Discovery : 扫描微应用
Discovery-->>CLI : 返回应用列表
alt start命令
CLI->>State : 检查构建状态
State-->>CLI : 返回状态信息
loop 每个应用
CLI->>Builder : 构建镜像
Builder->>Docker : 执行构建
Docker-->>Builder : 构建结果
CLI->>State : 更新状态
end
CLI->>Compose : 生成Compose配置
CLI->>Nginx : 生成Nginx配置
CLI->>Docker : 启动容器
else stop命令
CLI->>Docker : 停止容器
else clean命令
CLI->>Docker : 删除容器
CLI->>Docker : 删除镜像
CLI->>State : 清理状态文件
end
CLI-->>User : 返回执行结果
```

**图表来源**
- [src/cli.rs:297-463](file://src/cli.rs#L297-L463)
- [src/cli.rs:466-548](file://src/cli.rs#L466-L548)

**章节来源**
- [src/cli.rs:78-116](file://src/cli.rs#L78-L116)
- [src/cli.rs:297-463](file://src/cli.rs#L297-L463)

### 配置管理系统

配置管理模块负责处理主配置文件和应用配置：

```mermaid
classDiagram
class ProxyConfig {
+Vec~String~ scan_dirs
+String apps_config_path
+String nginx_config_path
+String compose_config_path
+String state_file_path
+String network_list_path
+String network_name
+u16 nginx_host_port
+String web_root
+String cert_dir
+Option~String~ domain
+from_file(path) Result~ProxyConfig~
+load_apps() Result~Vec~AppConfig~~
+save_apps(apps) Result
+validate(apps, discovered) Result
}
class AppConfig {
+String name
+Vec~String~ routes
+String container_name
+u16 container_port
+AppType app_type
+Option~String~ description
+Option~String~ nginx_extra_config
+Option~String~ path
+Vec~String~ docker_volumes
+Option~String~ run_as_user
}
class AppType {
<<enumeration>>
Static
Api
Internal
}
ProxyConfig --> AppConfig
AppConfig --> AppType
```

**图表来源**
- [src/config.rs:126-164](file://src/config.rs#L126-L164)
- [src/config.rs:24-68](file://src/config.rs#L24-L68)

#### 配置验证流程

```mermaid
flowchart TD
Start([开始配置验证]) --> CheckScanDirs["检查扫描目录"]
CheckScanDirs --> ScanEmpty{"扫描目录为空?"}
ScanEmpty --> |是| Error1["返回错误: scan_dirs 不能为空"]
ScanEmpty --> |否| CheckApps["检查应用数量"]
CheckApps --> CheckUniqueNames["验证应用名称唯一性"]
CheckUniqueNames --> DuplicateNames{"发现重复名称?"}
DuplicateNames --> |是| Error2["返回错误: 重复的应用名称"]
DuplicateNames --> |否| ValidateEachApp["验证每个应用配置"]
ValidateEachApp --> CheckAppType{"应用类型"}
CheckAppType --> |Static/Api| ValidateRoutes["验证路由配置"]
CheckAppType --> |Internal| ValidateInternal["验证内部应用配置"]
ValidateRoutes --> RoutesEmpty{"路由为空?"}
RoutesEmpty --> |是| Error3["返回错误: routes 不能为空"]
RoutesEmpty --> |否| NextApp["下一个应用"]
ValidateInternal --> CheckPath["检查路径存在性"]
CheckPath --> PathExists{"路径存在?"}
PathExists --> |否| Error4["返回错误: 路径不存在"]
PathExists --> CheckDockerfile["检查Dockerfile"]
CheckDockerfile --> DockerfileExists{"Dockerfile存在?"}
DockerfileExists --> |否| Error5["返回错误: 缺少Dockerfile"]
DockerfileExists --> NextApp
NextApp --> AllValid{"所有应用验证通过?"}
AllValid --> |是| Success["配置验证成功"]
AllValid --> |否| Error6["返回验证错误"]
Error1 --> End([结束])
Error2 --> End
Error3 --> End
Error4 --> End
Error5 --> End
Error6 --> End
Success --> End
```

**图表来源**
- [src/config.rs:221-347](file://src/config.rs#L221-L347)

**章节来源**
- [src/config.rs:178-218](file://src/config.rs#L178-L218)
- [src/config.rs:221-347](file://src/config.rs#L221-L347)

### 应用发现模块

应用发现模块负责扫描指定目录，自动发现微应用：

```mermaid
sequenceDiagram
participant Scanner as 目录扫描器
participant FS as 文件系统
participant Parser as 配置解析器
participant Validator as 验证器
Scanner->>FS : 遍历扫描目录
FS-->>Scanner : 返回目录项
loop 每个目录项
Scanner->>FS : 检查micro-app.yml存在
FS-->>Scanner : 返回检查结果
alt 发现micro-app.yml
Scanner->>Parser : 解析micro-app.yml
Parser-->>Scanner : 返回应用配置
Scanner->>Validator : 验证应用配置
Validator-->>Scanner : 返回验证结果
alt 验证通过
Scanner->>FS : 检查Dockerfile存在
FS-->>Scanner : 返回Dockerfile路径
Scanner->>Scanner : 添加到应用列表
else 验证失败
Scanner->>Scanner : 跳过该应用
end
else 未发现micro-app.yml
Scanner->>Scanner : 跳过该目录
end
end
Scanner-->>Scanner : 生成唯一应用名称
Scanner-->>Scanner : 检查容器名称唯一性
Scanner-->>Scanner : 返回发现的应用列表
```

**图表来源**
- [src/discovery.rs:235-352](file://src/discovery.rs#L235-L352)

#### 唯一应用名称生成算法

```mermaid
flowchart TD
Start([开始生成唯一名称]) --> GetAppName["获取应用目录名称"]
GetAppName --> CalcRelative["计算相对路径"]
CalcRelative --> StripPrefix["移除扫描目录前缀"]
StripPrefix --> HasComponents{"有路径组件?"}
HasComponents --> |否| UseAppName["使用应用目录名称"]
HasComponents --> |是| JoinComponents["连接路径组件"]
JoinComponents --> AddAppName["添加应用目录名称"]
AddAppName --> UseCombined["使用组合名称"]
UseAppName --> CheckDuplicate{"检查名称重复"}
UseCombined --> CheckDuplicate
CheckDuplicate --> Duplicate{"名称已存在?"}
Duplicate --> |是| Error["返回错误: 重复的微应用名称"]
Duplicate --> |否| Success["返回唯一名称"]
Error --> End([结束])
Success --> End
```

**图表来源**
- [src/discovery.rs:159-222](file://src/discovery.rs#L159-L222)

**章节来源**
- [src/discovery.rs:235-352](file://src/discovery.rs#L235-L352)
- [src/discovery.rs:159-222](file://src/discovery.rs#L159-L222)

### 状态管理模块

状态管理器负责跟踪微应用的构建状态，实现智能的增量构建：

```mermaid
classDiagram
class StateManager {
-PathBuf state_file_path
-HashMap~String,AppState~ states
+new(state_file_path) StateManager
+load() Result
+save() Result
+get_state(app_name) Option~&AppState~
+update_state(app_name, hash, image_exists) void
+remove_state(app_name) void
+needs_rebuild(app_name, current_hash) bool
+get_all_states() Iterator
}
class AppState {
+String app_name
+String hash
+DateTime~Utc~ last_build
+bool image_exists
}
StateManager --> AppState
```

**图表来源**
- [src/state.rs:31-56](file://src/state.rs#L31-L56)
- [src/state.rs:14-28](file://src/state.rs#L14-L28)

#### 目录哈希计算算法

```mermaid
flowchart TD
Start([开始计算目录哈希]) --> InitHasher["初始化SHA256哈希器"]
InitHasher --> WalkDir["遍历目录树"]
WalkDir --> CheckEntry{"处理目录项"}
CheckEntry --> |.git目录| SkipGit["跳过.git目录"]
CheckEntry --> |普通文件| ReadFile["读取文件内容"]
CheckEntry --> |目录| Continue["继续遍历"]
ReadFile --> UpdateHash["更新文件内容哈希"]
Continue --> WalkDir
SkipGit --> WalkDir
UpdateHash --> WalkDir
WalkDir --> Done{"遍历完成?"}
Done --> |否| CheckEntry
Done --> |是| Finalize["计算最终哈希值"]
Finalize --> Success["返回哈希值"]
Success --> End([结束])
```

**图表来源**
- [src/state.rs:195-233](file://src/state.rs#L195-L233)

**章节来源**
- [src/state.rs:40-186](file://src/state.rs#L40-L186)
- [src/state.rs:195-233](file://src/state.rs#L195-L233)

### 构建器模块

构建器模块负责 Docker 镜像的构建过程：

```mermaid
sequenceDiagram
participant Builder as 构建器
participant FS as 文件系统
participant Docker as Docker引擎
Builder->>FS : 检查Dockerfile存在
FS-->>Builder : 返回Dockerfile路径
Builder->>FS : 检查构建上下文
FS-->>Builder : 返回上下文路径
alt 禁用缓存
Builder->>Docker : 执行docker build --no-cache
else 启用缓存
Builder->>Docker : 执行docker build
end
Docker-->>Builder : 返回构建结果
Builder->>Builder : 解析环境变量文件
Builder->>Docker : 添加构建参数
Docker-->>Builder : 执行构建
alt 构建成功
Builder->>Builder : 记录构建日志
else 构建失败
Builder->>Builder : 返回错误信息
end
```

**图表来源**
- [src/builder.rs:20-120](file://src/builder.rs#L20-L120)

#### 环境变量处理流程

```mermaid
flowchart TD
Start([开始处理环境变量]) --> CheckEnvFile{"检查.env文件"}
CheckEnvFile --> |存在| ReadEnv["读取.env文件内容"]
CheckEnvFile --> |不存在| SkipEnv["跳过环境变量处理"]
ReadEnv --> ParseLines["逐行解析"]
ParseLines --> CheckLine{"检查行内容"}
CheckLine --> |空行| SkipLine["跳过空行"]
CheckLine --> |注释行| SkipComment["跳过注释"]
CheckLine --> |键值对| ExtractKV["提取键值对"]
ExtractKV --> AddArg["添加构建参数"]
SkipLine --> ParseLines
SkipComment --> ParseLines
AddArg --> ParseLines
ParseLines --> Done{"解析完成?"}
Done --> |否| CheckLine
Done --> |是| Success["返回构建参数"]
SkipEnv --> Success
Success --> End([结束])
```

**图表来源**
- [src/builder.rs:67-88](file://src/builder.rs#L67-L88)

**章节来源**
- [src/builder.rs:20-120](file://src/builder.rs#L20-L120)
- [src/builder.rs:67-88](file://src/builder.rs#L67-L88)

### Compose 配置生成器

Compose 生成器负责自动生成 docker-compose.yml 文件：

```mermaid
classDiagram
class ComposeConfig {
+Mapping services
+Mapping networks
}
class ComposeGenerator {
+generate_compose_config(apps, network_name, nginx_host_port,
env_files, web_root, cert_dir, domain) Result~String~
+generate_nginx_service() Mapping
+generate_app_service(app, network_name, env_file) Mapping
}
ComposeGenerator --> ComposeConfig
```

**图表来源**
- [src/compose.rs:11-16](file://src/compose.rs#L11-L16)
- [src/compose.rs:31-119](file://src/compose.rs#L31-L119)

#### SSL 证书检测流程

```mermaid
flowchart TD
Start([开始SSL证书检测]) --> CheckDomain{"检查域名配置"}
CheckDomain --> |无域名| NoSSL["返回SSL禁用"]
CheckDomain --> |有域名| CheckCertDir["检查证书目录"]
CheckCertDir --> BuildCertPath["构建证书文件路径"]
BuildCertPath --> TryCer["尝试.cer扩展名"]
TryCer --> CertExists{"证书文件存在?"}
CertExists --> |否| TryCrt["尝试.crt扩展名"]
CertExists --> |是| CheckKey["检查密钥文件"]
TryCrt --> CrtExists{"证书文件存在?"}
CrtExists --> |否| NoSSL
CrtExists --> |是| CheckKey
CheckKey --> KeyExists{"密钥文件存在?"}
KeyExists --> |否| NoSSL
KeyExists --> |是| EnableSSL["启用SSL配置"]
NoSSL --> End([结束])
EnableSSL --> End
```

**图表来源**
- [src/compose.rs:129-158](file://src/compose.rs#L129-L158)

**章节来源**
- [src/compose.rs:31-119](file://src/compose.rs#L31-L119)
- [src/compose.rs:129-158](file://src/compose.rs#L129-L158)

### Nginx 配置生成器

Nginx 配置生成器根据应用类型生成不同的路由规则：

```mermaid
classDiagram
class NginxGenerator {
+generate_nginx_config(apps, web_root, cert_dir, domain) Result~String~
+generate_http_server_block(apps, web_root) String
+generate_https_server_block(apps, web_root, cert_dir, domain) String
+generate_location_config(app, route) String
}
class LocationType {
<<enumeration>>
Static
Api
Internal
}
NginxGenerator --> LocationType
```

**图表来源**
- [src/nginx.rs:26-92](file://src/nginx.rs#L26-L92)
- [src/nginx.rs:418-536](file://src/nginx.rs#L418-L536)

#### 动态DNS解析机制

```mermaid
flowchart TD
Start([开始动态DNS解析]) --> SetVar["设置上游主机变量"]
SetVar --> CheckRoute{"检查路由类型"}
CheckRoute --> |根路径| DirectPass["直接转发到容器"]
CheckRoute --> |子路径| RewriteRule["生成重写规则"]
RewriteRule --> ApplyRewrite["应用重写规则"]
ApplyRewrite --> ProxyPass["转发到容器"]
DirectPass --> ProxyPass
ProxyPass --> SetHeaders["设置代理头"]
SetHeaders --> CacheConfig["配置缓存策略"]
CacheConfig --> End([配置完成])
```

**图表来源**
- [src/nginx.rs:418-536](file://src/nginx.rs#L418-L536)

**章节来源**
- [src/nginx.rs:26-92](file://src/nginx.rs#L26-L92)
- [src/nginx.rs:418-536](file://src/nginx.rs#L418-L536)

### 网络管理器

网络管理器负责 Docker 网络的创建和管理：

```mermaid
sequenceDiagram
participant NetworkMgr as 网络管理器
participant Docker as Docker引擎
NetworkMgr->>Docker : 检查网络是否存在
Docker-->>NetworkMgr : 返回网络状态
alt 网络不存在
NetworkMgr->>Docker : 创建Docker网络
Docker-->>NetworkMgr : 返回创建结果
else 网络存在
NetworkMgr->>NetworkMgr : 直接返回
end
NetworkMgr->>Docker : 查询网络详情
Docker-->>NetworkMgr : 返回网络信息
```

**图表来源**
- [src/network.rs:15-47](file://src/network.rs#L15-L47)

**章节来源**
- [src/network.rs:15-119](file://src/network.rs#L15-L119)

## 依赖关系分析

项目依赖关系图展示了各个模块之间的依赖关系：

```mermaid
graph TB
subgraph "外部依赖"
Serde[serde]
Clap[clap]
Log[log]
Chrono[chrono]
WalkDir[walkdir]
Sha2[sha2]
Regex[regex]
Tokio[tokio]
FsExtra[fs_extra]
PathDiff[pathdiff]
end
subgraph "内部模块"
Main[main.rs]
Lib[lib.rs]
CLI[cli.rs]
Config[config.rs]
Discovery[discovery.rs]
State[state.rs]
Builder[builder.rs]
Compose[compose.rs]
Nginx[nginx.rs]
Network[network.rs]
Volumes[volumes_config.rs]
end
Main --> Lib
Lib --> CLI
Lib --> Config
Lib --> Discovery
Lib --> State
Lib --> Builder
Lib --> Compose
Lib --> Nginx
Lib --> Network
Lib --> Volumes
CLI --> Config
CLI --> Discovery
CLI --> State
CLI --> Builder
CLI --> Compose
CLI --> Nginx
CLI --> Network
Config --> Serde
Config --> Log
Discovery --> Serde
Discovery --> Log
Discovery --> Volumes
State --> Serde
State --> Chrono
State --> Sha2
State --> WalkDir
Builder --> Log
Builder --> FsExtra
Compose --> Serde
Compose --> Log
Nginx --> Serde
Nginx --> Log
Nginx --> Chrono
Network --> Log
Volumes --> Serde
Volumes --> Log
```

**图表来源**
- [Cargo.toml:13-51](file://Cargo.toml#L13-L51)
- [src/lib.rs:6-18](file://src/lib.rs#L6-L18)

**章节来源**
- [Cargo.toml:13-51](file://Cargo.toml#L13-L51)
- [src/lib.rs:6-18](file://src/lib.rs#L6-L18)

## 性能考虑

### 构建缓存优化

micro_proxy 实现了智能的构建缓存机制，通过目录哈希值判断是否需要重新构建：

1. **增量构建**: 只有当目录内容发生变化时才重新构建镜像
2. **哈希计算**: 使用 SHA256 算法计算目录内容的哈希值
3. **状态持久化**: 将构建状态保存到状态文件中

### 并行处理

项目使用 tokio 异步运行时，支持并发处理多个微应用的构建任务。

### 内存管理

- 使用智能指针和所有权模型避免内存泄漏
- 合理使用引用避免不必要的数据拷贝
- 及时释放不再使用的资源

## 故障排查指南

### 常见问题及解决方案

#### 1. 端口冲突问题

**问题症状**: 启动时提示端口已被占用

**排查步骤**:
```bash
# 检查端口占用情况
sudo lsof -i :80
sudo lsof -i :8080

# 修改配置文件中的端口号
vim proxy-config.yml
# 将 nginx_host_port 修改为未被占用的端口
```

**章节来源**
- [README.md:363-372](file://README.md#L363-L372)

#### 2. Docker 镜像构建失败

**问题症状**: 构建过程中出现错误

**排查步骤**:
```bash
# 查看详细的构建日志
micro_proxy start -v

# 检查 Dockerfile 是否正确
cat ./micro-apps/my-app/Dockerfile

# 检查构建上下文路径
ls -la ./micro-apps/my-app/

# 清理构建缓存后重试
micro_proxy start --force-rebuild
```

**章节来源**
- [src/builder.rs:95-120](file://src/builder.rs#L95-L120)

#### 3. Nginx 配置错误

**问题症状**: 访问应用时出现 502 或 504 错误

**排查步骤**:
```bash
# 检查 Nginx 配置语法
docker exec proxy-nginx nginx -t

# 查看 Nginx 错误日志
docker logs proxy-nginx | grep -i error

# 检查后端服务是否正常运行
docker ps -a
```

**章节来源**
- [src/nginx.rs:94-131](file://src/nginx.rs#L94-L131)

#### 4. 卷挂载权限问题

**问题症状**: 应用无法写入挂载的目录

**排查步骤**:
```bash
# 检查宿主机目录权限
ls -la ./data

# 检查容器内挂载点
docker exec <container-name> ls -la /app/data

# 查看容器详细信息
docker inspect <container-name> | grep -A 10 Mounts
```

**章节来源**
- [src/volumes_config.rs:145-196](file://src/volumes_config.rs#L145-L196)

#### 5. 网络连接问题

**问题症状**: 微应用间无法通信

**排查步骤**:
```bash
# 生成网络地址列表
micro_proxy network

# 检查 Docker 网络
docker network ls

# 测试容器间连接
docker exec <container1> ping <container2>
```

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

### 日志查看技巧

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

#### 2. 查看容器日志
```bash
# 查看所有容器日志
docker logs -f $(docker ps -aq)

# 查看特定容器日志
docker logs -f <container-name>
```

#### 3. 分析日志文件
项目会自动生成日志文件，文件名为包名称加上 .log 扩展名。

**章节来源**
- [src/cli.rs:81-88](file://src/cli.rs#L81-L88)

## 结论

micro_proxy 提供了一个完整的微应用开发和部署解决方案，具有以下特点：

1. **模块化设计**: 各个组件职责明确，易于维护和扩展
2. **智能缓存**: 通过状态管理和哈希计算实现高效的增量构建
3. **自动化程度高**: 从应用发现到容器启动的全流程自动化
4. **配置灵活**: 支持多种配置方式和自定义选项
5. **易于调试**: 完善的日志系统和故障排查工具

通过遵循本文档提供的工作流程和最佳实践，开发者可以高效地进行微应用的开发、测试和部署。

## 附录

### 开发环境搭建

#### 1. 系统要求
- Rust 1.56 或更高版本
- Docker Engine 20.10 或更高版本
- Docker Compose 1.29 或更高版本

#### 2. 安装步骤
```bash
# 克隆仓库
git clone https://github.com/cao5zy/proxy-config
cd proxy-config

# 安装依赖
cargo install

# 验证安装
micro_proxy --version
```

#### 3. 配置文件设置
```bash
# 复制示例配置文件
cp proxy-config.yml.example proxy-config.yml

# 编辑配置文件
vim proxy-config.yml
```

**章节来源**
- [README.md:48-68](file://README.md#L48-L68)
- [proxy-config.yml.example:1-53](file://proxy-config.yml.example#L1-L53)

### 开发工作流程

#### 1. 创建微应用
```bash
# 创建微应用目录
mkdir -p micro-apps/my-app

# 复制配置模板
cp micro-app.yml.example micro-apps/my-app/micro-app.yml

# 编写 Dockerfile
vim micro-apps/my-app/Dockerfile
```

#### 2. 开发和测试
```bash
# 启动微应用
micro_proxy start

# 查看状态
micro_proxy status

# 查看网络地址
micro_proxy network
```

#### 3. 调试和优化
```bash
# 启用详细日志
micro_proxy start -v

# 查看容器日志
docker logs -f <container-name>

# 清理和重新构建
micro_proxy clean --force
micro_proxy start --force-rebuild
```

**章节来源**
- [docs/micro-app-development.md:250-428](file://docs/micro-app-development.md#L250-L428)
- [README.md:70-112](file://README.md#L70-L112)

### 版本控制和持续集成

#### 1. Git 配置
```bash
# 添加 .gitignore
echo "proxy-config.state" >> .gitignore
echo "*.log" >> .gitignore
echo "apps-config.yml" >> .gitignore
```

#### 2. CI/CD 配置示例
```yaml
name: Build and Deploy

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Rust
      uses: actions-rs/toolchain@v1
      with:
        toolchain: stable
        override: true
    
    - name: Build
      run: cargo build --release
    
    - name: Test
      run: cargo test
    
    - name: Upload artifacts
      uses: actions/upload-artifact@v2
      with:
        name: micro-proxy
        path: target/release/micro_proxy
```

**章节来源**
- [.gitignore](file://.gitignore)
- [Cargo.toml:1-55](file://Cargo.toml#L1-L55)