# 安装指南

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [Cargo.toml](file://Cargo.toml)
- [src/main.rs](file://src/main.rs)
- [src/cli.rs](file://src/cli.rs)
- [src/error.rs](file://src/error.rs)
- [proxy-config.yml.example](file://proxy-config.yml.example)
- [deploy_to_local.sh](file://deploy_to_local.sh)
- [docs/micro-app-development.md](file://docs/micro-app-development.md)
- [docs/ssl-configuration.md](file://docs/ssl-configuration.md)
</cite>

## 目录
1. [简介](#简介)
2. [系统要求与前置依赖](#系统要求与前置依赖)
3. [安装方式概览](#安装方式概览)
4. [从 crates.io 安装（推荐）](#从-cratesio-安装推荐)
5. [从源码构建安装](#从源码构建安装)
6. [安装验证](#安装验证)
7. [常见安装问题与解决方案](#常见安装问题与解决方案)
8. [针对不同操作系统和环境的安装建议](#针对不同操作系统和环境的安装建议)
9. [卸载与清理](#卸载与清理)
10. [结语](#结语)

## 简介
micro_proxy 是一个用于管理微应用的工具，支持 Docker 镜像构建、容器管理、Nginx 反向代理配置等功能。本文档提供两种安装方式的完整指南：从 crates.io 安装（推荐）和从源码构建安装，并涵盖系统要求、前置依赖检查、安装命令执行过程、优缺点对比、常见问题与解决方案以及安装验证方法。

## 系统要求与前置依赖
- 操作系统
  - Linux、macOS、Windows（WSL2）
- 必需软件
  - Rust 工具链（cargo、rustc）
  - Docker Engine（含 docker 命令）
  - Docker Compose（支持 docker compose 或 docker-compose）
- 可选（HTTPS 证书）
  - acme.sh（用于 Let's Encrypt 证书申请与部署）

上述依赖在安装过程中会通过 crates.io 安装或源码构建自动满足，但建议在安装前确保系统已具备这些能力。

**章节来源**
- [Cargo.toml: 依赖声明:13-51](file://Cargo.toml#L13-L51)
- [src/cli.rs: Docker Compose 命令调用:127-170](file://src/cli.rs#L127-L170)

## 安装方式概览
- 方式一：从 crates.io 安装（推荐）
  - 优点：安装简单、版本稳定、自动依赖管理
  - 适用场景：大多数用户、生产环境、CI/CD 流水线
- 方式二：从源码构建安装
  - 优点：可获得最新功能、便于调试与二次开发
  - 适用场景：开发者、需要定制功能的高级用户

## 从 crates.io 安装（推荐）
- 步骤
  1) 确认系统已安装 Rust 工具链（cargo、rustc）
  2) 执行安装命令
  3) 等待 cargo 自动下载并安装依赖
  4) 安装完成后，micro_proxy 可直接使用
- 命令
  - cargo install micro_proxy
- 说明
  - 该命令会从 crates.io 下载并安装 micro_proxy 可执行文件
  - 安装过程会自动解析 Cargo.toml 中的依赖并进行编译

**章节来源**
- [README.md: 从 crates.io 安装步骤:50-54](file://README.md#L50-L54)

## 从源码构建安装
- 步骤
  1) 克隆仓库
  2) 进入项目目录
  3) 构建 release 版本
  4) 安装到本地
- 命令
  - git clone https://github.com/cao5zy/proxy-config
  - cd proxy-config
  - cargo build --release
  - cargo install --path .
- 说明
  - 该方式适合需要最新功能或进行二次开发的用户
  - 构建完成后，cargo install 会将二进制文件安装到本地可执行路径

**章节来源**
- [README.md: 从源码构建步骤:56-68](file://README.md#L56-L68)
- [deploy_to_local.sh: 源码构建与部署脚本:50-87](file://deploy_to_local.sh#L50-L87)

## 安装验证
- 验证安装
  - micro_proxy --version
  - micro_proxy --help
- 验证 Docker 与 Compose
  - docker --version
  - docker compose version 或 docker-compose --version
- 验证配置文件
  - 复制示例配置文件并根据需要修改
  - cp proxy-config.yml.example proxy-config.yml
- 验证微应用准备
  - 在每个微应用目录下创建 micro-app.yml 配置文件
  - cp micro-app.yml.example ./micro-apps/my-app/micro-app.yml

**章节来源**
- [src/main.rs: 主入口与帮助输出:6-24](file://src/main.rs#L6-L24)
- [src/cli.rs: CLI 参数解析与帮助:22-39](file://src/cli.rs#L22-L39)
- [README.md: 快速开始与配置说明:70-86](file://README.md#L70-L86)

## 常见安装问题与解决方案
- 权限问题
  - 症状：安装或运行时报权限不足
  - 解决：确保当前用户对 ~/.cargo/bin 有写入权限；必要时使用 sudo（不推荐）
- 网络问题
  - 症状：cargo install 无法下载依赖
  - 解决：检查网络连接；配置代理；或使用国内镜像源
- 依赖缺失
  - 症状：构建失败，提示找不到某些依赖
  - 解决：安装 Docker 与 Docker Compose；确保系统具备编译所需的工具链
- 端口冲突
  - 症状：启动后 Nginx 端口被占用
  - 解决：修改 proxy-config.yml 中的 nginx_host_port
- Docker 命令不可用
  - 症状：CLI 报错提示 docker compose 或 docker-compose 不可用
  - 解决：安装 Docker Desktop 或 Docker Engine；确保 docker 命令在 PATH 中

**章节来源**
- [src/cli.rs: Docker Compose 命令调用与错误处理:127-170](file://src/cli.rs#L127-L170)
- [README.md: 端口冲突与 Docker 命令检查:363-372](file://README.md#L363-L372)

## 针对不同操作系统和环境的安装建议
- Linux
  - 使用包管理器安装 Rust（如 rustup）与 Docker
  - 推荐使用 crates.io 安装，避免编译时间过长
- macOS
  - 使用 Homebrew 安装 Rust 与 Docker Desktop
  - 若使用 M1/M2 芯片，注意 Docker Desktop 的架构兼容性
- Windows（WSL2）
  - 在 WSL2 中安装 Rust 与 Docker Desktop（Windows 端）
  - 通过 WSL2 的 Linux 环境进行安装与运行
- CI/CD 环境
  - 使用 crates.io 安装以减少构建时间
  - 提前缓存 cargo registry 与依赖

**章节来源**
- [Cargo.toml: 依赖声明与版本约束:13-51](file://Cargo.toml#L13-L51)
- [README.md: 端口配置说明:277-289](file://README.md#L277-L289)

## 卸载与清理
- 卸载
  - cargo uninstall micro_proxy
- 清理
  - 删除生成的配置文件（如 nginx.conf、docker-compose.yml、apps-config.yml、proxy-config.state、network-addresses.txt）
  - 删除 Docker 网络（可选）
  - 清理 Docker 镜像与容器（可选）

**章节来源**
- [src/cli.rs: 清理命令实现:476-548](file://src/cli.rs#L476-L548)

## 结语
通过以上步骤，您可以顺利完成 micro_proxy 的安装与验证。若在安装过程中遇到问题，请参考“常见安装问题与解决方案”部分；如需配置 HTTPS 证书，可参考 SSL 配置指南文档。