Starlight-apk
1736bb5801
- 问题报告.md: 重新审查代码，更新路径和问题列表 - RELEASE_v1.2.1.md: 改为路线图，标注实际完成状态 - CODE_VERIFICATION_REPORT.md: 重新验证核心功能 - FATAL_FIXES_REPORT.md: 按当前代码重写 - ai.md: 清理无关内容，更新统计和路线图 - 项目的后续计划.md: 补充详细开发计划 - README.md: 添加功能说明提示 - RELEASE_v1.1.0.md: 添加历史存档标记
106 lines
5.6 KiB
Markdown
106 lines
5.6 KiB
Markdown
# 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 文档、默认值不一致 |
|
||
|
||
**最紧急的修复项**：
|
||
1. 实现 `oss/core/security/` 安全中间件（JWT/CSRF/输入验证）
|
||
2. 实现 `oss/core/ops/` 运维工具箱（健康检查/备份/监控）
|
||
3. 更新 WebUI 为可用的管理面板
|
||
4. 完善测试覆盖
|
||
5. 实现 HTTPS 支持
|