NebulaShell 代码审查报告
审查日期：2026-05-17
基于仓库最新代码（commit: 5fbc5cc）
一、当前代码状态概览
| 指标 |
数值 |
| Python 文件 |
61 |
| Python 代码行数 |
~9,481 |
| 总文件数 |
117 |
| 核心模块 |
oss/core/（含 http_api、nbpf、repl 子模块） |
| 官方插件 |
5（i18n, nodejs-adapter, plugin-bridge, plugin-storage, ws-api） |
| 独立插件 |
1（system-monitor，位于根目录） |
| 测试文件 |
16（tests/ 下 3 个 + oss/tests/ 下 13 个） |
二、已知问题（按严重程度排列）
🔴 CRITICAL
| # |
问题 |
位置 |
说明 |
| 1 |
WebUI 仍为 v1.1.0 静态页面 |
oss/webui/index.html |
显示 v1.1.0 版本号，数据硬编码（"13个活跃插件"等），未对接后端 API |
| 2 |
无 JWT/CSRF/输入验证中间件 |
oss/core/ |
RELEASE_v1.2.1 规划的 oss/core/security/ 目录不存在，安全中间件未实现 |
| 3 |
无防火墙/运维工具箱模块 |
oss/core/ |
oss/core/firewall/ 和 oss/core/ops/ 目录不存在 |
| 4 |
无 /metrics Prometheus 端点 |
oss/core/http_api/ |
健康检查端点和监控指标未实现 |
| 5 |
plugin-storage 部分方法实现可疑 |
oss/store/NebulaShell/plugin-storage/main.py |
keys()、delete() 等方法逻辑需要验证 |
| 6 |
HTTP API 路由空实现风险 |
oss/core/http_api/router.py |
路由处理逻辑需要核验 |
🟠 HIGH
| # |
问题 |
位置 |
说明 |
| 7 |
测试覆盖率不足 |
全部 |
16 个测试文件覆盖主要模块，但核心 HTTP 路由、安全中间件、NBPF 加载链路缺乏端到端测试 |
| 8 |
无配置 Schema 验证 |
oss/config/config.py |
写错配置 key 名静默使用默认值 |
| 9 |
多处 except: pass |
多处 |
异常被静默吞掉，不利于调试 |
| 10 |
CORS 配置验证 |
oss/core/http_api/ |
需要确认 CORS 头是否从配置读取而非硬编码 |
| 11 |
限流器线程安全问题 |
oss/core/http_api/rate_limiter.py |
需要验证线程锁和 deque 使用是否正确 |
| 12 |
无 HTTPS 支持 |
全部 |
所有通信明文传输 |
🟡 MEDIUM
| # |
问题 |
位置 |
说明 |
| 13 |
无统一错误响应格式 |
多处 |
有时 JSON 有时纯文本 |
| 14 |
无日志轮转文件日志 |
oss/logger/logger.py |
需要确认是否已实现 RotatingFileHandler |
| 15 |
无 CI/CD 配置更新 |
.github/workflows/ |
需要确认 CI 配置是否匹配当前测试结构 |
| 16 |
Dockerfile 缺少 .dockerignore |
.dockerignore |
文件存在但为空 |
| 17 |
全局状态单例 |
oss/config/config.py |
_global_config 单例模式 |
| 18 |
Dashboard 鉴权缺失 |
oss/webui/ |
WebUI 无登录鉴权 |
🟢 LOW
| # |
问题 |
位置 |
说明 |
| 19 |
ENABLE_ASYNC 配置项未使用 |
oss/config/config.py |
定义了但从未被引用 |
| 20 |
残留注释为中文 |
多处 |
限制贡献者范围 |
| 21 |
无 .env.example |
根目录 |
环境变量无参考文档 |
| 22 |
配置默认值不一致 |
oss/config/config.py |
HOST 默认值与实际读取逻辑需确认 |
三、历史问题状态追踪
以下问题来自 2026-05-04 的审查报告，当前状态已更新：
| 原问题 |
原等级 |
当前状态 |
说明 |
| plugin-storage 路径穿越 |
🔴 CRITICAL |
⚠️ 已重构 |
当前代码已完全重写，使用内存缓存 + 文件持久化，但需要验证新实现的安全性 |
| plugin-storage 方法实现错误 |
🔴 CRITICAL |
⚠️ 已重构 |
同上，方法签名和逻辑已变更，需要重新审查 |
| HTTP API 路由空实现 |
🔴 CRITICAL |
⚠️ 待验证 |
oss/core/http_api/router.py 存在，但需要确认路由逻辑是否完整 |
init() 空指针 |
🔴 CRITICAL |
✅ 已修复 |
对应插件不存在于当前仓库 |
| code-reviewer 不可用 |
🔴 CRITICAL |
✅ 已清理 |
该插件已从仓库移除 |
CORS * |
🟠 HIGH |
⚠️ 待验证 |
需要确认当前中间件实现 |
| 限流器线程安全 |
🟠 HIGH |
⚠️ 待验证 |
需要确认当前 rate_limiter.py 实现 |
| 插件加载器安全检查可绕过 |
🟠 HIGH |
✅ 已清理 |
旧版 plugin-loader 已不在仓库中 |
| 空方法/存根代码 |
🟠 HIGH |
⚠️ 部分修复 |
engine.py 已拆分为 27 行，但部分插件仍有存根 TODO |
| 重复中间件实现 |
🟡 MEDIUM |
✅ 已清理 |
旧版 store 目录已移除 |
| CSRF 导入缺失 |
🟡 MEDIUM |
⏳ 未修复 |
CSRF 防护尚未实现 |
| 静态资源缓存头 |
🟡 MEDIUM |
⏳ 未修复 |
WebUI 无缓存策略 |
| 配置不一致 |
🟢 LOW |
⚠️ 部分修复 |
HOST 默认值已调整，但仍有不一致 |
| 异常静默吞掉 |
🟢 LOW |
⚠️ 部分修复 |
部分 except: pass 已修复，但仍有残留 |
四、总结
| 等级 |
数量 |
关键项 |
| 🔴 CRITICAL |
6 |
WebUI 未更新、安全模块未实现、防火墙/运维缺失、无 metrics、plugin-storage 待验证、路由待核验 |
| 🟠 HIGH |
6 |
测试覆盖率、配置验证、except:pass、CORS、限流、HTTPS |
| 🟡 MEDIUM |
6 |
错误格式、日志轮转、CI、Docker、全局状态、鉴权 |
| 🟢 LOW |
4 |
未使用配置、中文注释、env 文档、默认值不一致 |
最紧急的修复项：
- 实现
oss/core/security/ 安全中间件（JWT/CSRF/输入验证）
- 实现
oss/core/ops/ 运维工具箱（健康检查/备份/监控）
- 更新 WebUI 为可用的管理面板
- 完善测试覆盖
- 实现 HTTPS 支持
Starlight-apk
1736bb5801