From c59e33f6e4dd64650c8435c85901c187b11f6378 Mon Sep 17 00:00:00 2001
From: Warren <warren@momentry.ddns.net>
Date: Fri, 19 Jun 2026 09:53:03 +0800
Subject: [PATCH] Add Caddy configuration management and performance
 optimization Phase 1-6

---
 AGENTS.md | 483 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 483 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 4748a20..c3168f4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1698,3 +1698,486 @@ cargo fmt --check                   # Pass
 cargo clippy                        # Pass (minor unused warnings)
 ```
 
+---
+
+## Caddy 配置管理
+
+### Caddyfile 位置
+
+**配置文件**：`/Users/accusys/momentry/etc/Caddyfile`
+
+**当前运行进程**：
+```bash
+ps aux | grep caddy
+# root 45966 ... /opt/homebrew/opt/caddy/bin/caddy run --config /Users/accusys/momentry/etc/Caddyfile
+```
+
+### 重启 Caddy 方法
+
+**方法1：系统重启（推荐）** ⭐⭐⭐⭐⭐
+```bash
+# 停止 Caddy
+sudo pkill -TERM caddy
+
+# 等待进程结束
+sleep 2
+
+# 启动 Caddy（使用现有配置）
+sudo /opt/homebrew/opt/caddy/bin/caddy run --config /Users/accusys/momentry/etc/Caddyfile &
+```
+
+**方法2：使用 Caddy reload** ⭐⭐⭐⭐
+```bash
+# Graceful reload（不中断现有连接）
+sudo /opt/homebrew/opt/caddy/bin/caddy reload --config /Users/accusys/momentry/etc/Caddyfile
+```
+
+**方法3：验证配置后重启** ⭐⭐⭐⭐⭐（最安全）
+```bash
+# 1. 验证配置语法
+sudo /opt/homebrew/opt/caddy/bin/caddy validate --config /Users/accusys/momentry/etc/Caddyfile
+
+# 2. 如果验证通过，reload
+sudo /opt/homebrew/opt/caddy/bin/caddy reload --config /Users/accusys/momentry/etc/Caddyfile
+```
+
+### 关键配置示例
+
+**M5 SFTPGo 反向代理**（Line 156-159）：
+```caddy
+# M5 SFTPGo
+m5sftpgo.momentry.ddns.net {
+    reverse_proxy 192.168.110.201:8080
+    import common_log m5_sftpgo_access
+}
+```
+
+**验证状态**：
+```bash
+curl -I https://m5sftpgo.momentry.ddns.net
+# HTTP/2 302
+# Server: SFTPGo/2.7.99-dev
+# Via: 1.1 Caddy
+```
+
+### 日志位置
+
+**日志目录**：`/Users/accusys/momentry/log/`
+
+**日志文件命名**：`{service}_access.log`（由 `import common_log {args[0]}` 定义）
+
+**日志轮转配置**（Line 14-23）：
+- `roll_size: 100mb`
+- `roll_keep: 5`
+- `roll_keep_for: 720h`（30天）
+
+---
+
+## MarkBase 性能优化方案（Phase 1-6）
+
+**当前性能基准**：
+- rsync 传输：712 KB/s（AES-128-CTR）
+- 对比 sftpgo：~30 MB/s（Go AES-GCM）
+- **差距**：约 42 倍 ⚠️⚠️⚠️⚠️⚠️
+
+### 性能瓶颈分析 ⭐⭐⭐⭐⭐
+
+**关键瓶颈**（按优先级排序）：
+
+| 瓶颈 | 位置 | 影响 | 优先级 |
+|------|------|------|--------|
+| **加密算法** | cipher.rs: AES-128-CTR + HMAC-SHA256 | ⭐⭐⭐⭐⭐ 最大 | **P0** |
+| **零拷贝缺失** | cipher.rs: plaintext_packet → encrypted_packet | ⭐⭐⭐⭐ 高 | **P1** |
+| **频繁 Vec 分配** | channel.rs: 30个 Vec::new() | ⭐⭐⭐ 中 | **P2** |
+| **随机padding** | cipher.rs: rand::thread_rng() | ⭐⭐ 低 | **P3** |
+| **poll机制** | channel.rs: nix::poll | ⭐⭐ 低 | **P3** |
+
+---
+
+### Phase 1：AES-256-GCM 升级 ⭐⭐⭐⭐⭐（P0 最高优先级）
+
+**目标**：从 AES-128-CTR + HMAC-SHA256 → AES-256-GCM AEAD
+
+**实施步骤**：
+1. 添加 AES-GCM 支持（`aes-gcm` crate）
+2. 修改 KEX 算法协商（kex.rs）：
+   ```rust
+   encryption_algorithms: "aes256-gcm@openssh.com,aes128-ctr"
+   ```
+3. 修改 cipher.rs（约 200 行）：
+   ```rust
+   type Aes256Gcm = AesGcm<Aes256, UInt<UInt<UInt<UInt<UTerm, B1>, B1>, B0>, B0>>; // 16-byte tag
+   
+   impl EncryptionContext {
+       pub fn encrypt_aead(&mut self, payload: &[u8]) -> Result<Vec<u8>> {
+           let cipher = Aes256Gcm::new(&self.key.into(), &self.iv.into());
+           let ciphertext = cipher.encrypt(&self.nonce, payload)?;
+           Ok(ciphertext)
+       }
+   }
+   ```
+4. 修改 packet 处理（cipher.rs:200-302）：
+   - 删除 MAC 计算（MtE 模式）
+   - 使用 GCM tag（16字节）
+   - 简化 packet 结构
+
+**预期收益**：
+- 性能提升：712 KB/s → 1.5 MB/s（翻倍）
+- 安全性提升：AEAD > MtE
+- 代码简化：减少 MAC 计算开销
+
+**OpenSSH 兼容性** ⭐⭐⭐⭐⭐：
+- AES-GCM：OpenSSH 8.0+ 支持
+- AES-CTR：OpenSSH 7.x fallback
+- **策略**：保留 AES-CTR fallback（确保兼容性）
+
+**风险评估** ⚠️⚠️⚠️：
+- KEX 协商逻辑修改（需要测试）
+- OpenSSH 兼容性验证（需要客户端测试）
+
+**测试验证**：
+```bash
+# OpenSSH client 连接测试
+ssh -vvv -p 2024 demo@127.0.0.1
+
+# 检查算法协商
+# debug1: kex: algorithm: curve25519-sha256
+# debug1: kex: host key algorithm: ssh-ed25519
+# debug1: kex: server->client cipher: aes256-gcm@openssh.com MAC: <implicit>
+```
+
+---
+
+### Phase 2：零拷贝优化 ⭐⭐⭐⭐（P1）
+
+**目标**：使用 sshbuf.rs 替代临时 Vec
+
+**已实现资源** ⭐⭐⭐⭐⭐：
+- `markbase-core/src/ssh_server/sshbuf.rs`（339行，参考 OpenSSH sshbuf.c）
+- `SshBuf::peek()` / `consume()` / `reserve()` / `append()`
+
+**实施步骤**：
+1. 修改 cipher.rs（约 50 行）：
+   ```rust
+   use super::sshbuf::SshBuf;
+   
+   pub fn new_zero_copy(
+       plaintext_payload: &[u8],
+       encryption_ctx: &mut EncryptionContext,
+   ) -> Result<Self> {
+       let mut buf = SshBuf::with_capacity(4 + 1 + plaintext_payload.len() + 16);
+       buf.reserve(4 + 1 + plaintext_payload.len() + 16);
+       
+       // 零拷贝写入
+       buf.write_u32(packet_length)?;
+       buf.write_u8(padding_length)?;
+       buf.append(plaintext_payload);
+       
+       // 零拷贝加密
+       cipher.apply_keystream(buf.as_mut_slice());
+       
+       Ok(Self { payload: buf.into_vec(), ... })
+   }
+   ```
+2. 修改 channel.rs（约 20 行）：
+   - 使用 `SshBuf` 替代 `Vec::new()`
+   - 预分配 buffer（避免扩容）
+
+**预期收益**：
+- 内存分配减少：30%
+- 性能提升：约 10%
+- memcpy 减少：每次 packet 处理减少 1-2 次
+
+**风险** ⚠️：低（纯优化，不影响协议）
+
+---
+
+### Phase 3：Buffer Pool ⭐⭐⭐⭐（P2）
+
+**目标**：预分配 buffer pool，避免频繁分配
+
+**实施步骤**：
+1. 创建 `BufferPool` 结构（约 100 行）：
+   ```rust
+   pub struct BufferPool {
+       pools: Vec<Vec<Vec<u8>>>,
+       sizes: Vec<usize>,
+       max_size: usize,
+   }
+   
+   impl BufferPool {
+       pub fn acquire(&mut self, size: usize) -> Vec<u8> {
+           // 从 pool 获取预分配 buffer
+           // 如果 pool 空，则新分配
+       }
+       
+       pub fn release(&mut self, buffer: Vec<u8>) {
+           // 归还 buffer 到 pool
+       }
+   }
+   ```
+2. 修改 channel.rs（约 30 行）：
+   ```rust
+   let pool = BufferPool::new(vec![64, 256, 1024, 4096, 16384]);
+   
+   // 使用 pool buffer
+   let mut buffer = pool.acquire(1024);
+   // ... 处理数据 ...
+   pool.release(buffer);
+   ```
+
+**预期收益**：
+- 内存分配减少：70%
+- GC 压力降低
+- 长期运行稳定性提升
+
+**风险** ⚠️：低（纯优化）
+
+---
+
+### Phase 4：并行加密 ⭐⭐⭐⭐⭐（P0 最高收益）
+
+**目标**：使用 rayon 并行加密多个 packet
+
+**实施步骤**：
+1. 添加 rayon 依赖：
+   ```toml
+   [dependencies]
+   rayon = "1.10"
+   ```
+2. 修改 cipher.rs（约 150 行）：
+   ```rust
+   use rayon::prelude::*;
+   
+   pub fn encrypt_batch(
+       payloads: Vec<&[u8]>,
+       encryption_ctx: &mut EncryptionContext,
+   ) -> Result<Vec<EncryptedPacket>> {
+       // ⭐⭐⭐⭐⭐ 预生成 keystream（避免 counter 冲突）
+       let keystreams = encryption_ctx.generate_keystreams(payloads.len());
+       
+       // 并行加密
+       let packets: Vec<EncryptedPacket> = payloads
+           .par_iter()
+           .enumerate()
+           .map(|(i, payload)| {
+               encrypt_with_keystream(payload, keystreams[i])
+           })
+           .collect();
+       
+       Ok(packets)
+   }
+   ```
+3. 修改 channel.rs（约 50 行）：
+   ```rust
+   // 批量处理 channel_data
+   let payloads: Vec<&[u8]> = channel_data_buffers.iter().map(|b| b.as_slice()).collect();
+   let packets = EncryptedPacket::encrypt_batch(payloads, encryption_ctx)?;
+   
+   // 批量写入
+   for packet in packets {
+       packet.write(stream)?;
+   }
+   ```
+
+**预期收益**：
+- 性能提升：1.5 MB/s → 6 MB/s（四倍）
+- CPU 利用率：单核 → 多核（充分利用）
+- 并发处理：支持多个 channel 同时加密
+
+**关键技术** ⭐⭐⭐⭐⭐：
+- **预生成 keystream**：避免 AES-CTR counter 冲突
+- **批量处理**：减少 stream write 调用次数
+- **并行加密**：rayon 自动调度到多核
+
+**风险** ⚠️⚠️⚠️⚠️：
+- packet 顺序需要保证（使用 enumerate）
+- counter 同步需要正确（预生成 keystream）
+- stream write 需要按序（批量处理时排序）
+
+---
+
+### Phase 5：ChaCha20-Poly1305 ⭐⭐⭐⭐⭐（OpenSSH 默认）
+
+**目标**：添加 ChaCha20-Poly1305 AEAD 支持
+
+**实施步骤**：
+1. 添加 `chacha20poly1305` crate：
+   ```toml
+   [dependencies]
+   chacha20poly1305 = "0.10"
+   ```
+2. 修改 KEX 协商（kex.rs）：
+   ```rust
+   encryption_algorithms: "chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-ctr"
+   ```
+3. 修改 cipher.rs（约 300 行）：
+   ```rust
+   use chacha20poly1305::{ChaCha20Poly1305, Key, Nonce, aead::{Aead, NewAead}};
+   
+   type ChaChaPoly = ChaCha20Poly1305;
+   
+   impl EncryptionContext {
+       pub fn encrypt_chacha(&mut self, payload: &[u8]) -> Result<Vec<u8>> {
+           let cipher = ChaChaPoly::new(&self.key.into());
+           let nonce = Nonce::from_slice(&self.iv[..12]);
+           let ciphertext = cipher.encrypt(nonce, payload)?;
+           Ok(ciphertext)
+       }
+   }
+   ```
+
+**预期收益**：
+- 性能提升：约 2 MB/s（CPU 无 AES-NI 时）
+- OpenSSH 兼容性：默认算法 ⭐⭐⭐⭐⭐
+- 安全性：RFC 8439 标准
+
+**OpenSSH 兼容性** ⭐⭐⭐⭐⭐：
+- ChaCha20-Poly1305：OpenSSH 6.5+ 支持
+- **优先级**：OpenSSH 默认选择（高于 AES-GCM）
+
+**风险** ⚠️⚠️⚠️：
+- 协议兼容性测试
+- KEX 协商顺序调整
+
+---
+
+### Phase 6：AES-NI 硬件加速 ⭐⭐⭐⭐⭐（自动支持）
+
+**目标**：利用 CPU AES-NI 硬件加速
+
+**当前状态** ⭐⭐⭐⭐⭐：
+- `aes` crate **自动支持 AES-NI**（无需修改）
+- Runtime 自动检测 CPU AES-NI 支持
+- 如果 CPU 支持 AES-NI，则自动使用硬件加速
+
+**验证方法**：
+```bash
+# 检查 CPU AES-NI 支持
+sysctl -a | grep aes
+# hw.optional.aes: 1  ← macOS AES-NI 支持
+
+# 或者
+cat /proc/cpuinfo | grep aes  # Linux
+# flags: ... aes ...
+```
+
+**预期收益**：
+- 性能提升：约 5-10 倍（相比纯软件 AES）
+- **无需修改代码**（aes crate 自动支持）
+
+**风险** ⚠️：无（自动支持）
+
+---
+
+### 性能优化总表 ⭐⭐⭐⭐⭐
+
+| Phase | 方案 | 性能提升 | 成本 | 风险 | 优先级 | 实施时间 |
+|-------|------|---------|------|------|--------|---------|
+| **Phase 6** | AES-NI 硬件加速 | ⭐⭐⭐⭐⭐ 5-10倍 | ⭐ 已自动支持 | ⚠️ 无 | **P0** | 0分钟 |
+| **Phase 1** | AES-256-GCM | ⭐⭐⭐⭐⭐ 翻倍 | ⭐⭐⭐ 200行 | ⚠️⚠️⚠️ 兼容性 | **P0** | 2小时 |
+| **Phase 4** | 并行加密（rayon） | ⭐⭐⭐⭐⭐ 四倍 | ⭐⭐⭐⭐ 150行 | ⚠️⚠️⚠️⚠️ counter | **P0** | 3小时 |
+| **Phase 5** | ChaCha20-Poly1305 | ⭐⭐⭐⭐⭐ 三倍 | ⭐⭐⭐⭐ 300行 | ⚠️⚠️⚠️ 协议 | **P1** | 4小时 |
+| **Phase 2** | 零拷贝（sshbuf） | ⭐⭐⭐ 10% | ⭐⭐ 50行 | ⚠️ 低 | **P2** | 1小时 |
+| **Phase 3** | Buffer Pool | ⭐⭐⭐ 15% | ⭐⭐⭐ 100行 | ⚠️ 低 | **P2** | 2小时 |
+
+---
+
+### 推荐实施顺序 ⭐⭐⭐⭐⭐
+
+**阶段1：立即实施（本周）**
+- ✅ Phase 6: AES-NI 硬件加速（已自动支持）
+- ⏳ Phase 1: AES-256-GCM AEAD 模式（最高收益）
+- ⏳ Phase 4: rayon 并行加密（四倍提升）
+
+**预期结果**：712 KB/s → 20 MB/s（28倍提升）⭐⭐⭐⭐⭐
+
+**阶段2：短期实施（下周）**
+- ⏳ Phase 2: 零拷贝优化（sshbuf.rs）
+- ⏳ Phase 5: ChaCha20-Poly1305（备选方案）
+
+**预期结果**：20 MB/s → 25 MB/s（进一步提升）
+
+**阶段3：中期实施（后续）**
+- ⏳ Phase 3: Buffer Pool（内存优化）
+
+**预期结果**：25 MB/s → 30 MB/s（稳定优化）
+
+---
+
+### 性能目标对比 ⭐⭐⭐⭐⭐
+
+| 阶段 | 目标性能 | 对比 sftpgo | 备注 |
+|------|---------|------------|------|
+| **当前** | 712 KB/s | ⭐⭐ 低于 42倍 | AES-128-CTR + HMAC |
+| **Phase 1+6** | 5 MB/s | ⭐⭐⭐⭐ 相当 | AES-GCM + AES-NI |
+| **Phase 4** | 20 MB/s | ⭐⭐⭐⭐⭐ 超越 66% | 并行加密 |
+| **Phase 2-5** | 25-30 MB/s | ⭐⭐⭐⭐⭐ 完全超越 | 全面优化 |
+
+---
+
+### OpenSSL 性能基准参考 ⭐⭐⭐⭐⭐
+
+```bash
+# AES-128-CTR（当前）
+openssl speed aes-128-ctr
+# 约 200 MB/s（纯加密）
+
+# AES-256-GCM（Phase 1）
+openssl speed aes-256-gcm
+# 约 800 MB/s（AEAD + AES-NI）
+
+# ChaCha20-Poly1305（Phase 5）
+openssl speed chacha20-poly1305
+# 约 400 MB/s（无AES-NI时）
+```
+
+---
+
+### 关键技术决策 ⭐⭐⭐⭐⭐
+
+**需要确认的决策**：
+
+1. **优先级选择**：
+   - ⭐⭐⭐⭐⭐ 立即实施 Phase 1+6（最高收益，本周完成）
+   - ⭐⭐⭐⭐ 优先 Phase 4（并行加密，下周完成）
+   - ⭐⭐⭐ 先做 Phase 2-3（低风险，后续完成）
+
+2. **OpenSSH 兼容性策略**：
+   - ⭐⭐⭐⭐⭐ AES-GCM + AES-CTR fallback（推荐）
+   - ⭐⭐⭐⭐ 仅 AES-GCM（新版本）
+   - ⭐⭐⭐ 仅 AES-CTR（保守）
+
+3. **性能目标**：
+   - ⭐⭐⭐⭐⭐ 目标 20 MB/s（超越 sftpgo，推荐）
+   - ⭐⭐⭐⭐ 目标 5 MB/s（相当于 sftpgo）
+   - ⭐⭐⭐ 目标 1.5 MB/s（翻倍即可）
+
+4. **测试验证方法**：
+   - ⭐⭐⭐⭐⭐ rsync 100MB 实际测试（推荐）
+   - ⭐⭐⭐⭐ OpenSSL benchmark
+   - ⭐⭐⭐ 单元测试
+
+---
+
+### 风险管理 ⭐⭐⭐⭐⭐
+
+**高风险 ⚠️⚠️⚠️⚠️⚠️**：
+- Phase 1 AES-GCM 兼容性：OpenSSH 8.0+ 支持
+  - **解决方案**：保留 AES-CTR fallback
+- Phase 4 并行加密 counter 同步：counter 必须按序递增
+  - **解决方案**：预生成 keystream（避免冲突）
+
+**中风险 ⚠️⚠️⚠️**：
+- Phase 5 ChaCha20-Poly1305 协议兼容：SSH 协议协商
+  - **解决方案**：参考 OpenSSH kex.c 实现
+
+**低风险 ⚠️**：
+- Phase 2-3 内存优化：纯代码优化
+  - **解决方案**：不影响协议兼容性
+
+---
+
+**最后更新**：2026-06-19 09:50
+**版本**：1.22（Caddy 配置管理 + 性能优化方案 Phase 1-6）
+