# 代理工具孵化记录

> 状态：孵化中 | 更新：2026-03-27

---

## 工具列表

| 工具 | 端口 | 状态 | 项目目录 |
|------|------|------|----------|
| mysql-proxy | 3307 | 可用 | `mysql-proxy` |
| ssh-proxy | 3308 | 可用 | `ssh-proxy` |
| mongo-proxy | 3309 | 可用 | `mongo-proxy` |
| redis-proxy | 3310 | 可用 | `redis-proxy` |

---

## 新增功能

### 2026-03-24

1. **redis-proxy** (新工具)
   - Redis HTTP 代理，会话复用
   - 支持 run/get/set/del/keys/info
   - CLI 模式 + HTTP API 双模式
   - 连接: flux_dev

2. **mongo-proxy** (新工具)
   - MongoDB HTTP 代理，会话复用
   - 支持 find/insert/update/delete/aggregate/count
   - CLI 模式 + HTTP API 双模式
   - 连接: suke_dev, suke_pro

### 2026-03-21

1. **ssh-proxy 断线重连** (P0)
   - exec 方法检测到会话失效时自动清除并重连
   - 修复 get_or_create_session TOCTOU 竞态条件

2. **日志智能分级** (P1)
   - 慢请求告警: >3s WARN, >10s ERROR
   - 退出码识别: exitCode 0/1/-1 视为正常，>=2 或 127 标记 ERROR
   - UTF-8 安全截断

3. **服务器配置扩展** (P1)
   - 新增 server1 (一号机)、server2 (二号机)、ai_sg (新加坡 AI 机器)
   - 共 5 台服务器

4. **代码优化** (P2)
   - 移除未使用的 async-trait 依赖
   - 用 time crate 替换 40 行手写日期计算
   - 清理未使用字段

### 2026-03-20

1. **ssh-proxy russh 迁移** (P0)
   - 从 ssh2 迁移到 russh，原生支持 ed25519 密钥
   - 修复了 ed25519 认证失败问题
   - 使用 async/await 原生 API

### 2026-03-19

1. **请求日志** (P0)
   - 设置环境变量启用：`MYSQL_PROXY_LOG` / `SSH_PROXY_LOG`
   - 日志格式：JSON，每行一条记录

2. **ssh-proxy CLI JSON 输出** (P1)
   ```bash
   ssh-proxy exec -n flux_dev -c "docker ps" -F json
   ```

3. **ssh-proxy 动态添加服务器** (P2)
   ```bash
   ssh-proxy add-server -n myserver -H 192.168.1.100 -u root -p password
   # 或 API
   curl -X POST http://127.0.0.1:3308/servers/add \
     -H "Content-Type: application/json" \
     -d '{"name":"myserver","host":"192.168.1.100","user":"root","password":"secret"}'
   ```

4. **API 错误友好提示**
   - 错误时返回 `usage` 字段，引导正确使用

### 2026-03-18

- mysql-proxy 动态添加连接 API
- ssh-proxy Windows 路径修复
- ssh-proxy 读取错误日志修复

---

## 实测性能

| 操作 | 代理 | 直连 | 提升 |
|------|------|------|------|
| mysql 首次查询 | ~150ms | ~500ms | 3x |
| mysql 复用会话 | ~50ms | ~500ms | 10x |
| ssh 首次执行 | ~900ms | ~1500ms | 1.7x |
| ssh 复用会话 | ~100-200ms | ~1500ms | 7-15x |

---

## AI 推荐使用方式

> **优先使用 CLI 模式**，命令简洁

```bash
# MySQL 查询 (CLI 优先)
mysql-proxy cli -c flux_dev -e "SELECT VERSION()"

# MySQL JSON 输出
mysql-proxy cli -c flux_dev -e "SHOW TABLES" -F json

# MySQL 执行 DML
mysql-proxy cli -c flux_dev -e "UPDATE users SET status=1" -x

# SSH 执行 (CLI 优先)
ssh-proxy exec -n flux_dev -c "docker ps"

# SSH JSON 输出
ssh-proxy exec -n flux_dev -c "docker ps" -F json

# 列出服务器
ssh-proxy servers
mysql-proxy connections
```

**HTTP API (复杂场景)**：
```bash
# MySQL
curl -X POST http://127.0.0.1:3307/query \
  -H "Content-Type: application/json" \
  -d '{"conn":"flux_dev","sql":"SELECT VERSION()"}'

# SSH
curl -X POST http://127.0.0.1:3308/exec \
  -H "Content-Type: application/json" \
  -d '{"server":"flux_dev","command":"docker ps"}'
```

**降级方案** (代理不可用)：
```bash
mysql -h<host> -u<user> -p<password> -D<database> -e "<SQL>"
ssh <user>@<host> "<command>"
```

**优势**：
- CLI 命令简洁，AI 友好
- JSON 格式输出，易于解析
- 会话复用，响应快
- 错误提示友好

---

## 代码审查 (2026-03-27)

> 12 维度并行审查：架构一致性、错误处理、安全性、性能、DRY、日志、配置管理、CLI 一致性、边界条件、依赖、资源清理、代码度量

### 必须修复

| # | 问题 | 文件 | 说明 | 状态 |
|---|------|------|------|------|
| 1 | .gitignore 未覆盖 mongo/redis 配置 | `.gitignore` | 含真实密码，随时可能被 `git add` 提交 | ✅ |
| 2 | Redis 密码无 URL 编码 | `redis-proxy/src/config.rs` | 密码含 `@` `:` 时 URL 解析失败 | ✅ |
| 3 | mongo urlencoding 不完整 | `mongo-proxy/src/config.rs` | 只编码 5 字符，mysql 编码 19 字符 | ✅ |
| 4 | Redis 无重连机制 | `redis-proxy/src/db.rs` | Redis 重启后持续失败 5 分钟直到 idle timeout | ✅ |
| 5 | mysql-proxy handler 阻塞 tokio runtime | `mysql-proxy/src/handler.rs` | 同步 DB 操作未用 spawn_blocking，阻塞 worker 线程 | ✅ |
| 6 | 全部失败路径无日志 | 所有 handler.rs (4 项目) | 约 36 个 map_err/?? 路径跳过 logger.log() | ✅ |
| 7 | with_error() 从未调用 | 所有 logger.rs (4 项目) | 错误日志 level 永远是 INFO | ✅ |

### 建议改进

| # | 问题 | 文件 | 说明 |
|---|------|------|------|
| 8 | get_conn TOCTOU 竞态 | mysql/mongo/redis `db.rs` | 释放锁后重建，可能重复创建连接 |
| 9 | mysql `--config` 占用 `-c` | `mysql-proxy/src/main.rs:22` | 与 `--conn` 冲突 |
| 10 | LogEntry 字段不一致 | 4 个 `logger.rs` | server/sql/rows/exitCode 各有缺失 |
| 11 | logger.rs 等 ~300 行重复 | 4 个项目 | RequestLogger/LogEntry/辅助函数高度重复 |
| 12 | ssh-proxy 无 SSH disconnect | `ssh-proxy/src/session.rs` | cleanup 只移除 HashMap 不发 disconnect |
| 13 | 无 graceful shutdown | 4 个 `main.rs` | Ctrl+C 不等待进行中请求 |
| 14 | redis-proxy 降级提示单行 | `redis-proxy/src/main.rs:52` | 其他 3 个用多行格式 |
| 15 | mongo-proxy JSON 模式打印耗时 | `mongo-proxy/src/cli.rs:86` | 破坏 JSON 输出纯度 |
| 16 | redis-proxy 无 JSON 输出 | `redis-proxy/src/cli.rs` | 其他 3 个都支持 -F json |
| 17 | mongo insert/update 缺 usage 连接列表 | `mongo-proxy/src/handler.rs:224,256` | find/count 有但 insert/update 没有 |
| 18 | ssh-proxy 未使用 russh-keys 依赖 | `ssh-proxy/Cargo.toml` | beta 版本，代码用 russh::keys |
| 19 | tokio features = ["full"] 过宽 | 4 个 `Cargo.toml` | 实际只需 rt-multi-thread/net/time/sync |
| 20 | 日志写入阻塞 tokio | 4 个 `logger.rs` | 同步 writeln 阻塞 worker 线程 |

### 代码度量

| 项目 | 行数 | 文件数 | 最长函数 | unwrap | clone | unsafe |
|------|------|--------|---------|-------|-------|
| mysql-proxy | 1,209 | 6 | query() 74行 | 10 | 18 | 0 |
| ssh-proxy | 997 | 6 | exec() 49行 | 0 | 17 | 0 |
| mongo-proxy | 1,422 | 6 | find() 38行 | 9 | 11 | 0 |
| redis-proxy | 964 | 6 | run_cmd() 19行 | 10 | 30 | 0 |
| **合计** | **4,592** | **24** | -- | **29** | **76** | **0** |

> 无 unsafe 代码，无 TODO/FIXME，嵌套深度最大 3 层，函数最长 74 行。代码质量良好。

---

## 已知问题

### ssh-proxy

- 暂无 (ed25519 已支持)

### mysql-proxy

- 暂无

---

## 待优化

- [ ] 提取 proxy-common 公共 crate (logger/config/error/cli 基础)
- [ ] HTTP API 认证机制 (当前仅依赖 127.0.0.1 绑定)
- [ ] SSH 主机密钥验证 (当前无条件信任)
- [ ] redis-proxy 改用 redis::aio::ConnectionManager (避免 spawn_blocking)
- [ ] 日志写入改为 channel + 后台线程 (避免阻塞 tokio)
- [ ] 统一 graceful shutdown (with_graceful_shutdown)
- [x] .gitignore 补充 mongo/redis 配置文件
- [x] redis/mongo URL 编码对齐 mysql