rust-work/INCUBATOR.md

代理工具孵化记录

状态：孵化中 | 更新：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)

   ssh-proxy exec -n flux_dev -c "docker ps" -F json
   

3. ssh-proxy 动态添加服务器 (P2)

   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 模式，命令简洁

# 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 (复杂场景)：

# 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"}'

降级方案 (代理不可用)：

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)
• .gitignore 补充 mongo/redis 配置文件
• redis/mongo URL 编码对齐 mysql