acmex

AcmeX 项目架构设计文档

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

📋 目录

架构概览
分层设计
核心模块
依赖关系
扩展性设计
性能优化

架构概览

整体架构图

┌─────────────────────────────────────────────────────────┐
│                    应用层 (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 负责驱动订单、挑战和最终签发的全流程。支持状态汇报和异步执行。

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

2.2 Orchestrator Trait

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

#[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 流程：

提交订单: POST /api/orders 返回 202 Accepted 及 task_id。
后台处理: 服务器在后台线程启动 Provisioner。
状态轮询: 用户通过 GET /api/orders/:id 检查进度。
结果获取: 任务完成后，用户通过 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 提供商扩展

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. 存储后端扩展

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. 中间件扩展

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 类型扩展

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

[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. 连接池

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

2. Nonce 缓存

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

This site is open source. Improve this page.