# 微应用配置

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

## 更新摘要
**变更内容**
- 新增代理超时配置功能：proxy_connect_timeout、proxy_read_timeout、proxy_send_timeout 三个字段
- 更新 API 类型应用的 Nginx 代理配置，支持精细化超时控制
- 扩展微应用配置模型，支持可选的代理超时参数
- 更新配置验证和生成流程，确保超时配置正确应用

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

## 简介
本指南面向使用 micro_proxy 的开发者与运维人员，系统讲解微应用配置文件 micro-app.yml 的完整配置方法与最佳实践。重点涵盖三类应用类型（Static、API、Internal）的配置差异、路由与容器配置、卷映射与权限、以及应用发现与配置解析流程。文档同时提供配置验证规则、常见问题与解决方案，帮助你高效、安全地搭建与维护微服务集群。

**更新** 本版本新增了代理超时配置功能，允许用户为 API 类型应用精确控制 Nginx 代理的连接建立、读取和发送超时时间，提供更精细的代理控制能力。

## 项目结构
micro_proxy 通过"主配置文件 + 微应用配置文件 + 卷配置文件"的分层设计，实现对多微应用的自动化发现、校验、生成与部署。核心文件与职责如下：
- 主配置文件 proxy-config.yml：定义扫描目录、输出路径、网络与端口等全局参数
- 微应用配置 micro-app.yml：定义单个微应用的路由、容器、类型、描述与额外 Nginx 配置
- 卷配置 micro-app.volumes.yml：定义卷映射与运行用户，独立于 micro-app.yml
- 动态配置 apps-config.yml：由 micro_proxy 自动生成，汇总扫描到的微应用完整配置

```mermaid
graph TB
PC["proxy-config.yml<br/>主配置"] --> DISC["应用发现<br/>扫描目录"]
DISC --> MAP["MicroApp<br/>封装配置与文件"]
MAP --> MAC["micro-app.yml<br/>微应用配置"]
MAP --> VOL["micro-app.volumes.yml<br/>卷配置"]
MAP --> DOCK["Dockerfile<br/>镜像构建"]
MAP --> APP["AppConfig<br/>动态配置"]
APP --> NGINX["nginx.conf<br/>反向代理"]
APP --> COMPOSE["docker-compose.yml<br/>容器编排"]
```

**图表来源**
- [discovery.rs:224-352](file://src/discovery.rs#L224-L352)
- [micro_app_config.rs:37-53](file://src/micro_app_config.rs#L37-L53)
- [volumes_config.rs:56-82](file://src/volumes_config.rs#L56-L82)
- [config.rs:76-123](file://src/config.rs#L76-L123)

**章节来源**
- [README.md: 配置说明:164-235](file://README.md#L164-L235)
- [docs/micro-app-development.md: 配置文件总览:25-55](file://docs/micro-app-development.md#L25-L55)

## 核心组件
- 微应用配置模型（MicroAppConfig）：负责解析 micro-app.yml，提供基础字段与验证，现支持代理超时配置
- 应用配置模型（AppConfig）：负责将 MicroAppConfig 转换为动态配置，补充路径、卷与运行用户
- 应用发现（discover_micro_apps）：扫描目录，收集有效微应用并做去重与校验
- 卷配置模型（VolumesConfig）：解析 micro-app.volumes.yml，生成权限初始化脚本与 Docker Compose 卷格式
- 错误类型（Error）：统一错误分类，便于定位与处理

**章节来源**
- [micro_app_config.rs: MicroAppConfig:10-107](file://src/micro_app_config.rs#L10-L107)
- [config.rs: AppConfig/AppType:11-68](file://src/config.rs#L11-L68)
- [discovery.rs: MicroApp/discover_micro_apps:12-352](file://src/discovery.rs#L12-L352)
- [volumes_config.rs: VolumesConfig:43-205](file://src/volumes_config.rs#L43-L205)
- [error.rs: 错误类型:6-46](file://src/error.rs#L6-L46)

## 架构总览
下面的时序图展示了从扫描到生成配置的完整流程，以及配置验证与生成 Nginx/Compose 的关键节点。

```mermaid
sequenceDiagram
participant CLI as "命令行"
participant DISC as "应用发现"
participant MAP as "MicroApp"
participant MAC as "MicroAppConfig"
participant VOL as "VolumesConfig"
participant CFG as "ProxyConfig/AppsConfig"
participant GEN as "配置生成器"
CLI->>DISC : 扫描 scan_dirs
DISC->>MAP : 读取 micro-app.yml 与 Dockerfile
MAP->>MAC : 解析 micro-app.yml含代理超时配置
MAP->>VOL : 解析 micro-app.volumes.yml
MAP->>MAP : 校验 Dockerfile/.env/卷配置
MAP-->>DISC : 返回 MicroApp
DISC-->>CFG : 生成 AppConfig 列表
CFG->>CFG : 校验应用名称/容器名唯一性
CFG->>GEN : 生成 nginx.conf/docker-compose.yml含超时配置
GEN-->>CLI : 输出配置文件
```

**图表来源**
- [discovery.rs: MicroApp::from_directory:49-91](file://src/discovery.rs#L49-L91)
- [discovery.rs: MicroApp::validate:94-119](file://src/discovery.rs#L94-L119)
- [discovery.rs: to_app_config:121-147](file://src/discovery.rs#L121-L147)
- [config.rs: ProxyConfig::validate:220-347](file://src/config.rs#L220-L347)
- [config.rs: AppsConfig::save_to_file:101-122](file://src/config.rs#L101-L122)

## 详细组件分析

### 微应用配置模型（MicroAppConfig）
- 字段与约束
  - routes：数组，Static/API 类型必需；Internal 类型忽略（可为空）
  - container_name：字符串，全局唯一，不可为空
  - container_port：u16，不可为 0
  - app_type：字符串，取值限定为 static、api、internal
  - description：可选
  - nginx_extra_config：可选，仅对 Static/API 有效
  - **proxy_connect_timeout：u64，可选，API 类型应用的连接建立超时时间（秒）**
  - **proxy_read_timeout：u64，可选，API 类型应用的读取超时时间（秒）**
  - **proxy_send_timeout：u64，可选，API 类型应用的发送超时时间（秒）**
- 解析与验证
  - 从文件读取 YAML 并反序列化
  - 运行时校验：名称、端口、类型、路由与 Internal 类型的特殊规则
- 用途
  - 作为 discovery 阶段的基础输入
  - 作为 AppConfig 的来源之一

**章节来源**
- [micro_app_config.rs: 结构体与验证:10-107](file://src/micro_app_config.rs#L10-L107)

### 应用配置模型（AppConfig）
- 字段与约束
  - name：动态生成的唯一标识
  - routes：静态/API 类型必需；Internal 类型可为空
  - container_name/container_port：来自 micro-app.yml
  - app_type：枚举（Static/Api/Internal）
  - description/nginx_extra_config：可选
  - path：微应用绝对路径（动态生成）
  - docker_volumes：从 micro-app.volumes.yml 转换而来
  - run_as_user：从 micro-app.volumes.yml 加载
  - **proxy_connect_timeout：u64，可选，API 类型应用的连接建立超时时间（秒）**
  - **proxy_read_timeout：u64，可选，API 类型应用的读取超时时间（秒）**
  - **proxy_send_timeout：u64，可选，API 类型应用的发送超时时间（秒）**
- 生成逻辑
  - discovery 阶段将 MicroApp 转换为 AppConfig
  - name 生成规则：基于 scan_dir 相对路径与最后一级目录名组合
  - docker_volumes 转换：volumes 列表转为 "source:target" 字符串
- 校验规则
  - 所有应用名称唯一
  - Static/API：必须存在于扫描结果中，且 routes 非空
  - Internal：必须提供 path，且该路径存在 Dockerfile；routes/nginx_extra_config 将被忽略

**章节来源**
- [config.rs: AppConfig/AppType:11-68](file://src/config.rs#L11-L68)
- [config.rs: ProxyConfig::validate:220-347](file://src/config.rs#L220-L347)
- [discovery.rs: MicroApp::to_app_config:121-147](file://src/discovery.rs#L121-L147)

### 应用发现与名称生成
- 发现规则
  - 遍历 scan_dirs 的直接子目录
  - 目录必须同时包含 micro-app.yml 与 Dockerfile
  - 生成唯一 name：若为直接子目录仅用目录名；否则用"相对路径_目录名"
- 去重与校验
  - 名称去重
  - 容器名去重
  - Dockerfile 存在性与 .env 存在性告警
- 转换为 AppConfig
  - 将 MicroAppConfig/AppType/卷配置转换为 AppConfig，包括代理超时配置

**章节来源**
- [discovery.rs: discover_micro_apps:235-352](file://src/discovery.rs#L235-L352)
- [discovery.rs: generate_unique_app_name:147-222](file://src/discovery.rs#L147-L222)
- [discovery.rs: MicroApp::from_directory:49-91](file://src/discovery.rs#L49-L91)

### 卷配置模型（VolumesConfig）
- 字段与约束
  - volumes：列表，每项包含 source/target/permissions
  - run_as_user：可选，格式为 "uid:gid" 或用户名
- 校验规则
  - source/target 非空
  - uid/gid 为 0 时发出安全风险警告
  - run_as_user 非空字符串
- 功能
  - 生成权限初始化脚本（chown）
  - 转换为 Docker Compose 卷格式（"source:target"）

**章节来源**
- [volumes_config.rs: VolumesConfig:43-205](file://src/volumes_config.rs#L43-L205)

### 应用类型详解与配置差异
- Static（静态/前端）
  - 对外暴露，需要 Nginx 反向代理
  - routes 必须配置，nginx_extra_config 可选
  - 建议配合 SPA 的 nginx.conf 与权限配置
- API（后端服务）
  - 对外暴露，请求路径完整透传
  - routes 必须配置，nginx_extra_config 可选（常用于 CORS/预检）
  - **支持代理超时配置，可精确控制连接建立、读取和发送超时时间**
- Internal（内部服务）
  - 不对外暴露，仅用于微服务间通信
  - routes 必须为空；nginx_extra_config 无效
  - 必须提供 path，且该路径存在 Dockerfile

**章节来源**
- [docs/micro-app-development.md: 类型选择速查表:46-54](file://docs/micro-app-development.md#L46-L54)
- [config.rs: ProxyConfig::validate Internal 校验:273-322](file://src/config.rs#L273-L322)

### 路由配置（routes）
- Static/API：必须提供至少一个路由前缀
- Internal：必须为空数组
- 生成的 Nginx 配置将把请求转发到对应容器的 container_port

**章节来源**
- [micro_app_config.rs: routes 验证:87-94](file://src/micro_app_config.rs#L87-L94)
- [config.rs: ProxyConfig::validate Static/API 校验:250-272](file://src/config.rs#L250-L272)

### 容器配置（container_name、container_port）
- container_name：全局唯一，避免冲突
- container_port：不可为 0，需与容器内监听端口一致
- 生成的 Compose/Nginx 将使用这些值进行端口映射与上游配置

**章节来源**
- [micro_app_config.rs: container_name/container_port 验证:59-75](file://src/micro_app_config.rs#L59-L75)
- [config.rs: ProxyConfig::validate:220-347](file://src/config.rs#L220-L347)

### Nginx 额外配置（nginx_extra_config）
- 仅对 Static/API 有效
- 支持自定义响应头、CORS、特殊路径转发等
- Internal 类型忽略该字段

**章节来源**
- [micro_app_config.rs: nginx_extra_config 字段:30-32](file://src/micro_app_config.rs#L30-L32)
- [config.rs: AppConfig 描述:48-51](file://src/config.rs#L48-L51)

### 代理超时配置（proxy_connect_timeout、proxy_read_timeout、proxy_send_timeout）
- **适用范围**：仅对 API 类型应用有效
- **数据类型**：u64，单位为秒，可选配置
- **默认值**：未配置时使用 60 秒
- **作用机制**：
  - proxy_connect_timeout：控制 Nginx 与后端应用建立连接的超时时间
  - proxy_read_timeout：控制 Nginx 从后端应用读取响应的超时时间
  - proxy_send_timeout：控制 Nginx 向后端应用发送请求的超时时间
- **配置优先级**：微应用配置 > 默认值（60秒）
- **Nginx 配置生成**：在 API 类型的 location 块中生成对应的 proxy_connect_timeout、proxy_read_timeout、proxy_send_timeout 指令

**章节来源**
- [micro_app_config.rs: 代理超时字段:34-39](file://src/micro_app_config.rs#L34-L39)
- [config.rs: AppConfig 代理超时字段:69-79](file://src/config.rs#L69-L79)
- [nginx.rs: API 超时配置:496-518](file://src/nginx.rs#L496-L518)

### 卷映射与权限（docker_volumes/run_as_user）
- docker_volumes：从 micro-app.volumes.yml 的 volumes 列表转换而来
- run_as_user：从 micro-app.volumes.yml 直接加载
- 权限初始化：在容器启动前执行 chown（可选递归）
- 安全建议：避免使用 root 权限（uid/gid=0），尽量使用非特权用户

**章节来源**
- [volumes_config.rs: generate_permission_init_script:145-196](file://src/volumes_config.rs#L145-L196)
- [volumes_config.rs: to_docker_compose_volumes:198-204](file://src/volumes_config.rs#L198-L204)
- [docs/micro-app-development.md: 卷配置文件:90-180](file://docs/micro-app-development.md#L90-L180)

### 配置解析与生成流程
- 主配置 proxy-config.yml：定义扫描目录、输出路径、网络与端口
- 应用发现：扫描目录，收集包含 micro-app.yml 与 Dockerfile 的微应用
- 配置转换：MicroAppConfig → AppConfig，补充 path、卷与运行用户，包括代理超时配置
- 校验：名称/容器名唯一性、Static/API 的路由存在性、Internal 的路径与 Dockerfile
- 生成：apps-config.yml、nginx.conf、docker-compose.yml

**章节来源**
- [proxy-config.yml.example:5-31](file://proxy-config.yml.example#L5-L31)
- [discovery.rs: discover_micro_apps:235-352](file://src/discovery.rs#L235-L352)
- [config.rs: AppsConfig::from_file/save_to_file:76-123](file://src/config.rs#L76-L123)
- [config.rs: ProxyConfig::load_apps/save_apps:205-218](file://src/config.rs#L205-L218)

## 依赖关系分析
- 模块耦合
  - discovery 依赖 micro_app_config 与 volumes_config
  - config 依赖 discovery 生成的 AppConfig
  - volumes_config 与 micro_app_config 独立，通过 discovery 组合
- 外部依赖
  - YAML 解析（serde_yaml）
  - 日志（log/dumbo_log）
  - 命令行（clap）
  - 异步运行时（tokio）
  - 文件系统与路径处理（fs_extra/pathdiff）

```mermaid
graph LR
DISC["discovery.rs"] --> MAC["micro_app_config.rs"]
DISC --> VOL["volumes_config.rs"]
CFG["config.rs"] --> DISC
CFG --> MAC
CFG --> VOL
NGINX["nginx.rs"] --> CFG
COMPOSE["compose.rs"] --> CFG
ERR["error.rs"] --> DISC
ERR --> CFG
ERR --> VOL
```

**图表来源**
- [discovery.rs:6-8](file://src/discovery.rs#L6-L8)
- [config.rs:6-9](file://src/config.rs#L6-L9)
- [volumes_config.rs:6-8](file://src/volumes_config.rs#L6-L8)
- [error.rs:3-4](file://src/error.rs#L3-L4)

**章节来源**
- [Cargo.toml: 依赖列表:13-52](file://Cargo.toml#L13-L52)

## 性能考量
- 扫描复杂度：O(N) 遍历 scan_dirs 的直接子目录，N 为目录数量
- 解析与校验：YAML 解析与字段校验为 O(k)（k 为配置项数），整体开销较小
- I/O 优化：批量读取与缓存（如路径哈希）减少重复构建
- 建议
  - 控制 scan_dirs 数量与层级，避免过多目录导致扫描时间增长
  - 合理拆分微应用，避免单个应用体积过大影响构建与启动
  - **合理设置代理超时时间，避免过长或过短影响性能和用户体验**

## 故障排查指南
- 常见错误类型
  - 配置错误（Config）：字段缺失、取值非法、重复名称/容器名
  - 发现错误（Discovery）：缺少 Dockerfile、相对路径计算失败
  - YAML 解析错误（Yaml）：语法错误或类型不匹配
- 典型问题与解决
  - routes 为空：Static/API 类型必须提供至少一个路由
  - container_name 重复：确保全局唯一
  - Internal 缺少 path/Dockerfile：Internal 类型必须提供有效路径与 Dockerfile
  - 卷权限为 root：避免 uid/gid=0，改用非特权用户
  - nginx_extra_config 无效：仅对 Static/API 生效
  - **代理超时配置无效：仅对 API 类型应用生效，Static/Internal 类型忽略**
  - **超时时间设置不当：可能导致连接超时或资源占用过高**
- 排查步骤
  - 查看日志：启用详细日志模式
  - 检查 apps-config.yml：确认动态配置生成是否成功
  - 验证 Dockerfile 与 .env 是否存在
  - 使用状态/网络命令辅助定位
  - **检查 nginx.conf 中的代理超时配置是否正确生成**

**章节来源**
- [error.rs: 错误类型:6-46](file://src/error.rs#L6-L46)
- [README.md: 故障排查:328-420](file://README.md#L328-L420)
- [config.rs: ProxyConfig::validate:220-347](file://src/config.rs#L220-L347)
- [volumes_config.rs: validate:84-143](file://src/volumes_config.rs#L84-L143)

## 结论
micro-app.yml 提供了清晰、可扩展的微应用配置能力。通过严格的字段校验、灵活的卷与权限配置、完善的发现与生成流程，以及新增的代理超时控制功能，micro_proxy 能够稳定地支撑多微服务的统一入口与内部通信。遵循本文的配置规范与最佳实践，可显著降低配置成本与运维风险。

**更新** 新增的代理超时配置功能为 API 类型应用提供了更精细的 Nginx 代理控制能力，用户可以根据应用的实际需求精确调整连接建立、读取和发送超时时间，提升系统的稳定性和性能表现。

## 附录

### 配置项总览与取值范围
- routes
  - 类型：数组（字符串）
  - 取值：任意非空路径前缀
  - 限制：Static/API 必须提供；Internal 必须为空
- container_name
  - 类型：字符串
  - 取值：任意非空字符串，全局唯一
- container_port
  - 类型：u16
  - 取值：1–65535，不可为 0
- app_type
  - 类型：字符串
  - 取值：static、api、internal
- description
  - 类型：字符串（可选）
- nginx_extra_config
  - 类型：字符串（可选，仅 Static/API）
- **proxy_connect_timeout**
  - 类型：u64（可选，仅 API 类型）
  - 取值：正整数，单位秒，默认 60
  - 作用：控制 Nginx 与后端应用建立连接的超时时间
- **proxy_read_timeout**
  - 类型：u64（可选，仅 API 类型）
  - 取值：正整数，单位秒，默认 60
  - 作用：控制 Nginx 从后端应用读取响应的超时时间
- **proxy_send_timeout**
  - 类型：u64（可选，仅 API 类型）
  - 取值：正整数，单位秒，默认 60
  - 作用：控制 Nginx 向后端应用发送请求的超时时间
- docker_volumes
  - 类型：数组（字符串，由 micro-app.volumes.yml 转换）
  - 格式：source:target
- run_as_user
  - 类型：字符串（可选，格式：uid:gid 或用户名）

**章节来源**
- [micro_app_config.rs: 字段定义:10-39](file://src/micro_app_config.rs#L10-L39)
- [config.rs: AppConfig 字段:24-79](file://src/config.rs#L24-L79)
- [volumes_config.rs: VolumesConfig 字段:43-53](file://src/volumes_config.rs#L43-L53)

### 应用类型配置示例与最佳实践
- Static 示例
  - routes：["/"]
  - container_name：唯一容器名
  - container_port：80
  - nginx_extra_config：可选，用于缓存与安全头
- API 示例
  - routes：["/api"]
  - container_name：唯一容器名
  - container_port：后端监听端口
  - nginx_extra_config：可选，用于 CORS/预检
  - **proxy_connect_timeout：可选，如 30（秒）**
  - **proxy_read_timeout：可选，如 120（秒）**
  - **proxy_send_timeout：可选，如 60（秒）**
- Internal 示例
  - routes：[]
  - container_name：唯一容器名
  - container_port：内部服务端口（如 6379）
  - path：包含 Dockerfile 的宿主机路径

**章节来源**
- [docs/micro-app-development.md: Static/API/Internal 示例:271-486](file://docs/micro-app-development.md#L271-L486)
- [README.md: 微应用配置示例:205-233](file://README.md#L205-L233)

### 应用发现机制与配置解析过程
- 发现：扫描 scan_dirs，过滤包含 micro-app.yml 与 Dockerfile 的目录
- 名称生成：基于相对路径与目录名生成唯一 name
- 校验：名称/容器名唯一性、Static/API 路由存在性、Internal 路径与 Dockerfile
- 转换：MicroAppConfig → AppConfig，补充 path、卷与运行用户，包括代理超时配置
- 生成：apps-config.yml、nginx.conf、docker-compose.yml

**章节来源**
- [discovery.rs: discover_micro_apps:235-352](file://src/discovery.rs#L235-L352)
- [discovery.rs: generate_unique_app_name:147-222](file://src/discovery.rs#L147-L222)
- [config.rs: AppsConfig::from_file/save_to_file:76-123](file://src/config.rs#L76-L123)

### 代理超时配置最佳实践
- **连接超时（proxy_connect_timeout）**
  - 适用于数据库连接池、外部 API 调用等场景
  - 建议设置为 30-120 秒，避免过短导致连接失败
- **读取超时（proxy_read_timeout）**
  - 适用于大数据传输、文件下载等场景
  - 建议设置为 60-300 秒，确保大文件传输完成
- **发送超时（proxy_send_timeout）**
  - 适用于大请求体上传、实时数据推送等场景
  - 建议设置为 60-180 秒，平衡性能与稳定性
- **配置原则**
  - 三者关系：proxy_connect_timeout ≤ proxy_send_timeout ≤ proxy_read_timeout
  - 根据业务场景调整：高延迟网络适当增加超时时间
  - 监控异常：定期检查超时错误日志，优化配置参数

**章节来源**
- [nginx.rs: API 超时配置:496-518](file://src/nginx.rs#L496-L518)
- [config.rs: ProxyConfig::validate:220-347](file://src/config.rs#L220-L347)