acmex 0.8.0

# AcmeX 项目架构设计文档

**文档版本**: 1.0  
**项目版本**: v0.4.0  
**更新时间**: 2026-02-07  
**编辑**: houseme

---

## 📋 目录

1. [架构概览](#架构概览)
2. [分层设计](#分层设计)
3. [核心模块](#核心模块)
4. [依赖关系](#依赖关系)
5. [扩展性设计](#扩展性设计)
6. [性能优化](#性能优化)

---

## 架构概览

### 整体架构图

```
┌─────────────────────────────────────────────────────────┐
│                    应用层 (Application)                 │
│  ┌─────────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │   CLI Tools     │  │  Web Server  │  │  Libraries │ │
│  └────────┬────────┘  └──────┬───────┘  └──────┬─────┘ │
└───────────┼──────────────────┼──────────────────┼────────┘
            │                  │                  │
┌───────────▼──────────────────▼──────────────────▼────────┐
│              编排层 (Orchestration)                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  │
│  │Provisioner│ │Validator │ │Renewer   │  │Cleanup  │  │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘  │
│  ┌──────────────────────────────────────────────────────┐│
│  │             Task State Machine (Orchestrator)        ││
│  └──────────────────────────────────────────────────────┘│
└───────────┬─────────────────────────────────────────┬────┘
            │                                         │
┌───────────▼─────────────────────────────────────────▼────┐
│              业务逻辑层 (Business Logic)                  │
│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────────┐│
│  │ Account │ │  Order  │ │Challenge │ │ Certificate    ││
│  └─────────┘ └─────────┘ └──────────┘ └────────────────┘│
│  ┌──────────────────────────────────────────────────────┐│
│  │          Protocol (ACME v2 / RFC 8555)              ││
│  │  Directory | Nonce | JWS | Authorization | Objects  ││
│  └──────────────────────────────────────────────────────┘│
└───────────┬──────────────────────────────────────┬────────┘
            │                                      │
┌───────────▼──────────────────────────────────────▼────────┐
│           传输和支持层 (Transport & Support)              │
│  ┌──────────────┐ ┌─────────────┐ ┌────────────────────┐ │
│  │HTTP Client   │ │Retry Policy │ │Rate Limiter        │ │
│  └──────────────┘ └─────────────┘ └────────────────────┘ │
│  ┌──────────────┐ ┌─────────────┐ ┌────────────────────┐ │
│  │Config Mgmt   │ │Crypto (ECC) │ │Encoding (B64/PEM) │ │
│  └──────────────┘ └─────────────┘ └────────────────────┘ │
└───────────┬──────────────────────────────────────┬────────┘
            │                                      │
┌───────────▼──────────────────────────────────────▼────────┐
│         持久化和观测层 (Persistence & Observability)      │
│  ┌─────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│  │File Storage │ │Redis Storage │ │Encrypted Storage   │ │
│  └─────────────┘ └──────────────┘ └────────────────────┘ │
│  ┌──────────────────────────────────────────────────────┐ │
│  │   Metrics (Prometheus) | Logging (Tracing) | Events │ │
│  └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

---

## 分层设计

### 1. 应用层 (Application Layer)

负责用户交互和外部集成。

#### 1.1 CLI 工具 (`src/cli/`)

- **主要职责**: 命令行参数解析、用户交互、输出格式化
- **核心文件**:
    - `args.rs` - 使用 clap 的参数定义
    - `commands/obtain.rs` - 证书申请命令
    - `commands/renew.rs` - 证书续期命令
    - `commands/daemon.rs` - 后台守护进程
    - `commands/info.rs` - 证书信息查看
- **关键接口**: `CommandHandler`, `OutputFormatter`

#### 1.2 Web 服务器 (`src/server/`) [计划中]

- **主要职责**: REST API、Webhook 处理、健康检查
- **使用框架**: Axum
- **端点规划**:
    - `GET /api/certificates` - 列表
    - `POST /api/certificates` - 新建
    - `GET /api/status` - 健康检查

#### 1.3 库 API (`src/lib.rs`)

- **主要职责**: 为外部应用提供 Rust API
- **导出**: `AcmeClient`, `AcmeConfig`, 各类型和 trait

### 2. 编排层 (Orchestration Layer)

协调各业务模块，实现高层工作流。

#### 2.1 Provisioner (证书申请编排器)

`CertificateProvisioner` 负责驱动订单、挑战和最终签发的全流程。支持状态汇报和异步执行。

```rust
pub struct CertificateProvisioner {
    pub task_id: String,
    pub status: Arc<RwLock<OrchestrationStatus>>,
    // ...
}
```

#### 2.2 Orchestrator Trait

所有编排器实现 `Orchestrator` trait，提供统一的异步任务处理能力。

```rust
#[async_trait]
pub trait Orchestrator: Send + Sync {
    async fn execute(&mut self) -> Result<()>;
    fn status(&self) -> OrchestrationStatus;
}
```

### 3. REST API 异步架构 (v0.7.0)

AcmeX 采用 "Post-Task-Polling" 模式处理耗时的 ACME 流程：

1. **提交订单**: `POST /api/orders` 返回 `202 Accepted` 及 `task_id`。
2. **后台处理**: 服务器在后台线程启动 `Provisioner`。
3. **状态轮询**: 用户通过 `GET /api/orders/:id` 检查进度。
4. **结果获取**: 任务完成后，用户通过 `GET /api/certificates/:id` 下载证书。

---

## 核心模块

### 模块通信流

```
CLI 用户输入
    ↓
┌─────────────────────┐
│ AcmeClient (主入口) │
└──────────┬──────────┘
           ↓
┌──────────────────────────────────────┐
│ CertificateProvisioner (编排器)      │
└──┬───────────────┬──────────────┬────┘
   ↓               ↓              ↓
AccountMgr    OrderManager   ChallengeSolver
   ↓               ↓              ↓
Protocol        Protocol      DNS/HTTP
JWS/Directory   Nonce         Validation
   ↓               ↓              ↓
HttpClient (传输层，重试+限流)
   ↓
ACME 服务器
```

### 关键数据结构

```
Certificate
├── certificate: X509 PEM
├── private_key: PEM encoded
├── chain: Vec<Certificate>
├── not_before: DateTime
├── not_after: DateTime
├── domains: Vec<String>
└── serial_number: String

Order
├── id: String
├── status: OrderStatus
├── identifiers: Vec<Identifier>
├── authorizations: Vec<Authorization>
├── certificate_url: Option<String>
├── finalize_url: String
└── created_at: DateTime

Authorization
├── identifier: Identifier
├── status: AuthorizationStatus
├── challenges: Vec<Challenge>
├── expires: DateTime
└── wildcard: bool

Challenge
├── type: ChallengeType
├── url: String
├── status: ChallengeStatus
├── token: String
└── validated: Option<DateTime>
```

---

## 依赖关系

### 外部依赖

```
acmex
├── async-trait        # 异步 trait 支持
├── axum              # Web 框架
├── base64            # Base64 编码
├── clap              # CLI 参数
├── jiff              # 时间处理
├── hickory-resolver  # DNS 解析
├── pem               # PEM 编码/解码
├── rcgen             # CSR/证书生成
├── reqwest           # HTTP 客户端
├── serde             # 序列化
├── sha2              # 哈希算法
├── tokio             # 异步运行时
├── tracing           # 日志和追踪
├── aws-lc-rs 或 ring # 加密后端
└── redis (可选)       # Redis 支持
```

### 内部依赖关系

```
lib.rs (公开 API)
├── protocol/ (底层)
│   ├── directory.rs
│   ├── nonce.rs
│   ├── jws.rs
│   └── objects.rs
├── account/ (依赖 protocol)
├── order/ (依赖 account, protocol)
├── challenge/ (依赖 protocol, transport)
├── client/ (依赖 account, order, challenge)
├── storage/ (独立)
├── renewal/ (依赖 client, storage)
├── metrics/ (独立)
├── transport/ (底层)
├── crypto/ (底层)
└── cli/ (依赖所有)
```

---

## 扩展性设计

### Trait 系统

通过 trait 实现可插拔架构：

#### 1. DNS 提供商扩展

```rust
pub trait DnsProvider: Send + Sync {
    async fn create_txt_record(&self, domain: &str, value: &str) -> Result<String>;
    async fn delete_txt_record(&self, domain: &str, record_id: &str) -> Result<()>;
    async fn query_txt_record(&self, domain: &str) -> Result<Vec<String>>;
}
```

添加新提供商：

- 在 `src/dns/providers/` 下创建文件
- 实现 `DnsProvider` trait
- 通过 feature gate 启用

#### 2. 存储后端扩展

```rust
pub trait StorageBackend: Send + Sync {
    async fn save(&self, key: &str, value: &[u8]) -> Result<()>;
    async fn load(&self, key: &str) -> Result<Option<Vec<u8>>>;
    async fn delete(&self, key: &str) -> Result<()>;
}
```

支持的后端：

- FileStorage (默认)
- RedisStorage (feature: redis)
- EncryptedStorage (通用包装器)
- 自定义后端 (实现 trait)

#### 3. 中间件扩展

```rust
pub trait Middleware: Send + Sync {
    async fn before_request(&self, url: &str, method: &str) -> Result<()>;
    async fn after_response(&self, url: &str, response: &HttpResponse) -> Result<()>;
    async fn on_error(&self, url: &str, error: &AcmeError) -> Result<()>;
}
```

#### 4. Challenge 类型扩展

```rust
pub trait ChallengeSolver: Send + Sync {
    async fn prepare(&self, authorization: &Authorization) -> Result<()>;
    async fn validate(&self, authorization: &Authorization) -> Result<bool>;
    async fn cleanup(&self, authorization: &Authorization) -> Result<()>;
    fn challenge_type(&self) -> ChallengeType;
}
```

### Feature Flags

```toml
[features]
default = ["aws-lc-rs"]

# 加密后端
aws-lc-rs = ["dep:aws-lc-rs"]
ring-crypto = ["dep:ring"]

# 存储后端
redis = ["dep:redis"]

# DNS 提供商
dns-cloudflare = []
dns-digitalocean = []
dns-linode = []
dns-route53 = []
dns-azure = []      # 计划
dns-gcloud = []     # 计划

# CA 服务
google-ca = []
zerossl-ca = []

# 功能模块
metrics = []
cli = []
```

---

## 性能优化

### 1. 连接池

```rust
pub struct HttpClientConfig {
    pub pool_size: usize,
    pub timeout: Duration,
    pub follow_redirects: bool,
}
```

### 2. Nonce 缓存

```rust
pub struct NonceManager {
    pool: Vec<String>,  // 预缓存 nonce
    endpoint: String,
}
```

### 3. 并发处理

- 并行验证多个域名的挑战
- 使用 `tokio::spawn` 处理独立任务
- 异步 I/O 避免阻塞

### 4. 内存优化

- 使用 `Arc<T>` 共享所有权
- `Mutex` 而不是 `RwLock` 减少竞争
- 及时释放大对象

### 5. 缓存策略

- Directory 缓存 (可配置 TTL)
- DNS 解析结果缓存
- Certificate 元数据缓存

---

## 安全考虑

### 1. 密钥保护

- 使用 `zeroize` 清除敏感数据
- 密钥通过环境变量配置
- 支持加密存储

### 2. TLS 安全

- 强制使用 TLS 1.3
- 证书固定支持
- HSTS 支持

### 3. 请求验证

- JWS 签名验证
- Nonce 防重放
- 时间戳验证

### 4. 访问控制

- API 认证 (令牌)
- 速率限制
- IP 白名单

---

**文档版本**: 1.0  
**最后更新**: 2026-02-07  
**维护者**: houseme