CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
521 lines
13 KiB
Markdown
521 lines
13 KiB
Markdown
# SecuBox 模块验证指南
|
||
|
||
🌐 **语言：** [English](../docs/validation-guide.md) | [Français](../docs-fr/validation-guide.md) | 中文
|
||
|
||
**版本：** 1.0.0
|
||
**最后更新：** 2025-12-28
|
||
**状态：** 活跃
|
||
|
||
> **📚 完整参考：**
|
||
> 这是一份详细的验证指南。快速命令请参阅 [QUICK-START.md](quick-start.md)
|
||
>
|
||
> **相关文档：**
|
||
> - 完整指南：[DEVELOPMENT-GUIDELINES.md §8](development-guidelines.md#validation-checklist)
|
||
> - 提交前检查清单：[DEVELOPMENT-GUIDELINES.md §8.1](development-guidelines.md#pre-commit-checklist)
|
||
> - 部署后检查清单：[DEVELOPMENT-GUIDELINES.md §8.3](development-guidelines.md#post-deploy-checklist)
|
||
> - 权限指南：[PERMISSIONS-GUIDE.md](permissions-guide.md)
|
||
> - 自动化简报：[CODEX.md](codex.md)
|
||
|
||
---
|
||
|
||
## 另请参阅
|
||
|
||
- **快速命令：** [QUICK-START.md](quick-start.md)
|
||
- **权限参考：** [PERMISSIONS-GUIDE.md](permissions-guide.md)
|
||
- **自动化防护措施：** [CODEX.md](codex.md)
|
||
- **部署程序：** [DEVELOPMENT-GUIDELINES.md §9](development-guidelines.md#deployment-procedures)
|
||
|
||
本指南说明了在生成期间和 git push 之前对 SecuBox 模块执行的验证检查。
|
||
|
||
## 概述
|
||
|
||
SecuBox 使用多层验证方法：
|
||
|
||
1. **模块生成验证** - 验证新创建/修改的模块
|
||
2. **推送前验证** - 如果发现关键问题则阻止 git push
|
||
3. **运行时验证** - 对已部署模块的持续检查
|
||
|
||
## 验证工具
|
||
|
||
### 1. validate-module-generation.sh
|
||
|
||
在生成期间/之后对单个模块进行综合验证。
|
||
|
||
**用法：**
|
||
```bash
|
||
./secubox-tools/validate-module-generation.sh luci-app-cdn-cache
|
||
```
|
||
|
||
**执行的检查：**
|
||
- ✅ Makefile 的完整性和正确性
|
||
- ✅ RPCD 脚本命名约定（必须使用 `luci.` 前缀）
|
||
- ✅ RPCD 脚本可执行权限
|
||
- ✅ RPCD 脚本结构（list/call 处理程序）
|
||
- ✅ ACL 文件 JSON 有效性
|
||
- ✅ ACL 权限覆盖 RPCD 方法
|
||
- ✅ 菜单文件 JSON 有效性
|
||
- ✅ 菜单路径匹配视图文件位置
|
||
- ✅ JavaScript 视图文件存在
|
||
- ✅ JavaScript 严格模式使用
|
||
- ✅ RPC 方法调用匹配 RPCD 方法
|
||
- ✅ ubus 对象名称匹配 RPCD 脚本名称
|
||
- ✅ UCI 配置有效性（如果存在）
|
||
- ✅ 安全扫描（硬编码凭据、危险命令）
|
||
- ✅ 文档存在
|
||
|
||
**退出代码：**
|
||
- `0` - 所有检查通过
|
||
- `1` - 发现严重错误（模块不应部署）
|
||
|
||
### 2. pre-push-validation.sh
|
||
|
||
在允许 git push 之前验证所有模块。
|
||
|
||
**用法：**
|
||
```bash
|
||
# 自动（通过 git hook）：
|
||
git push # 验证自动运行
|
||
|
||
# 手动：
|
||
./secubox-tools/pre-push-validation.sh
|
||
```
|
||
|
||
**执行的检查：**
|
||
- ✅ Git 暂存更改检查
|
||
- ✅ 所有模块的 RPCD 命名约定
|
||
- ✅ 所有模块的菜单路径验证
|
||
- ✅ JSON 语法验证
|
||
- ✅ RPCD 可执行权限
|
||
- ✅ ACL 方法覆盖
|
||
- ✅ Makefile 验证
|
||
- ✅ 安全扫描
|
||
- ✅ 修改模块的完整模块验证
|
||
|
||
**退出代码：**
|
||
- `0` - 允许推送
|
||
- `1` - 阻止推送（严重错误）
|
||
|
||
### 3. validate-modules.sh
|
||
|
||
所有模块的快速验证（现有工具）。
|
||
|
||
**用法：**
|
||
```bash
|
||
./secubox-tools/validate-modules.sh
|
||
```
|
||
|
||
详情请参阅 `secubox-tools/README.md`。
|
||
|
||
## 安装 Git Hooks
|
||
|
||
启用 git push 前的自动验证：
|
||
|
||
```bash
|
||
./secubox-tools/install-git-hooks.sh
|
||
```
|
||
|
||
这将创建从 `.git/hooks/pre-push` 到 `secubox-tools/pre-push-validation.sh` 的符号链接。
|
||
|
||
## 关键命名约定
|
||
|
||
### 1. RPCD 脚本必须匹配 ubus 对象
|
||
|
||
**规则：** RPCD 脚本文件名必须与 JavaScript 中声明的 ubus 对象名称完全匹配。
|
||
|
||
**原因：** LuCI 的 RPC 系统根据文件名查找 RPCD 脚本。如果名称不匹配，您会得到：
|
||
- `RPC call failed with error -32000: Object not found`
|
||
- `Command failed: Method not found`
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
// JavaScript (htdocs/luci-static/resources/view/cdn-cache/overview.js)
|
||
var callStatus = rpc.declare({
|
||
object: 'luci.cdn-cache', // ← 必须匹配 RPCD 文件名
|
||
method: 'status'
|
||
});
|
||
```
|
||
|
||
```bash
|
||
# RPCD 脚本文件名必须是：
|
||
root/usr/libexec/rpcd/luci.cdn-cache # ← 精确为 'luci.cdn-cache'
|
||
```
|
||
|
||
**常见错误：**
|
||
- ❌ `root/usr/libexec/rpcd/cdn-cache`（缺少 `luci.` 前缀）
|
||
- ❌ `root/usr/libexec/rpcd/luci-cdn-cache`（使用短横线而非点号）
|
||
- ❌ `root/usr/libexec/rpcd/cdn_cache`（使用下划线）
|
||
|
||
**验证：**
|
||
```bash
|
||
# 检查命名：
|
||
./secubox-tools/validate-module-generation.sh luci-app-cdn-cache
|
||
|
||
# 查找：
|
||
# ✓ RPCD script follows naming convention (luci.* prefix)
|
||
# ✓ CRITICAL: RPCD script name matches ACL ubus object
|
||
```
|
||
|
||
### 2. 菜单路径必须匹配视图文件位置
|
||
|
||
**规则：** 菜单 JSON 的 `path` 条目必须对应实际的视图文件路径。
|
||
|
||
**原因：** LuCI 根据菜单中的路径加载视图。错误的路径 = HTTP 404。
|
||
|
||
**示例：**
|
||
|
||
```json
|
||
// 菜单 (root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json)
|
||
{
|
||
"action": {
|
||
"type": "view",
|
||
"path": "netifyd-dashboard/overview" // ← 必须匹配文件位置
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
# 视图文件必须存在于：
|
||
htdocs/luci-static/resources/view/netifyd-dashboard/overview.js
|
||
# ↑ 与菜单相同的路径 ↑
|
||
```
|
||
|
||
**常见错误：**
|
||
- ❌ 菜单：`"path": "netifyd/overview"` 但文件在 `view/netifyd-dashboard/overview.js`
|
||
- ❌ 菜单：`"path": "overview"` 但文件在 `view/netifyd-dashboard/overview.js`
|
||
|
||
**验证：**
|
||
```bash
|
||
# 检查路径：
|
||
./secubox-tools/validate-module-generation.sh luci-app-netifyd-dashboard
|
||
|
||
# 查找：
|
||
# ✓ Menu path 'netifyd-dashboard/overview' → view file EXISTS
|
||
```
|
||
|
||
### 3. 所有 ubus 对象必须使用 `luci.` 前缀
|
||
|
||
**规则：** 每个 ubus 对象声明必须以 `luci.` 开头
|
||
|
||
**原因：** LuCI 应用程序的一致命名约定。ACL 系统需要它。
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
// ✅ 正确：
|
||
object: 'luci.cdn-cache'
|
||
object: 'luci.system-hub'
|
||
object: 'luci.wireguard-dashboard'
|
||
|
||
// ❌ 错误：
|
||
object: 'cdn-cache' // 缺少 luci. 前缀
|
||
object: 'systemhub' // 缺少 luci. 前缀
|
||
```
|
||
|
||
**验证：**
|
||
```bash
|
||
# 检查约定：
|
||
./secubox-tools/validate-modules.sh
|
||
|
||
# 查找：
|
||
# ✓ ubus object 'luci.cdn-cache' follows naming convention
|
||
```
|
||
|
||
## 模块生成检查清单
|
||
|
||
生成新模块时使用此检查清单：
|
||
|
||
### 阶段 1：初始生成
|
||
|
||
- [ ] 创建模块目录：`luci-app-<模块名>/`
|
||
- [ ] 生成包含所有必填字段的 Makefile
|
||
- [ ] 在 `root/usr/libexec/rpcd/luci.<模块名>` 创建 RPCD 脚本
|
||
- [ ] 使 RPCD 脚本可执行：`chmod +x`
|
||
- [ ] 向 RPCD 添加 shebang：`#!/bin/sh`
|
||
- [ ] 实现 RPCD 方法（list、call、status 等）
|
||
- [ ] 创建包含 read/write 权限的 ACL 文件
|
||
- [ ] 创建包含正确路径的菜单 JSON
|
||
- [ ] 创建视图 JavaScript 文件
|
||
- [ ] 向所有 JS 文件添加 `'use strict';`
|
||
|
||
### 阶段 2：验证
|
||
|
||
- [ ] 运行模块生成验证：
|
||
```bash
|
||
./secubox-tools/validate-module-generation.sh luci-app-<模块名>
|
||
```
|
||
|
||
- [ ] 修复所有错误（关键）
|
||
- [ ] 查看所有警告（推荐）
|
||
|
||
### 阶段 3：集成验证
|
||
|
||
- [ ] 验证 RPCD 脚本名称与 ubus 对象匹配：
|
||
```bash
|
||
grep -r "object:" luci-app-<模块名>/htdocs --include="*.js"
|
||
ls -la luci-app-<模块名>/root/usr/libexec/rpcd/
|
||
# 名称必须完全匹配
|
||
```
|
||
|
||
- [ ] 验证菜单路径与视图文件匹配：
|
||
```bash
|
||
grep '"path":' luci-app-<模块名>/root/usr/share/luci/menu.d/*.json
|
||
ls -R luci-app-<模块名>/htdocs/luci-static/resources/view/
|
||
# 路径必须对齐
|
||
```
|
||
|
||
- [ ] 验证 ACL 权限覆盖所有 RPCD 方法：
|
||
```bash
|
||
grep 'case "$2"' luci-app-<模块名>/root/usr/libexec/rpcd/*
|
||
grep -A 20 '"ubus":' luci-app-<模块名>/root/usr/share/rpcd/acl.d/*.json
|
||
# 所有方法都应在 ACL 中
|
||
```
|
||
|
||
### 阶段 4：提交前
|
||
|
||
- [ ] 运行综合验证：
|
||
```bash
|
||
./secubox-tools/validate-modules.sh
|
||
```
|
||
|
||
- [ ] 查看安全扫描结果
|
||
- [ ] 检查 JSON 有效性：
|
||
```bash
|
||
find luci-app-<模块名> -name "*.json" -exec python3 -m json.tool {} \; > /dev/null
|
||
```
|
||
|
||
- [ ] 可选：在 RPCD 上运行 shellcheck：
|
||
```bash
|
||
shellcheck luci-app-<模块名>/root/usr/libexec/rpcd/*
|
||
```
|
||
|
||
### 阶段 5：Git 提交
|
||
|
||
- [ ] 暂存更改：
|
||
```bash
|
||
git add luci-app-<模块名>
|
||
```
|
||
|
||
- [ ] 使用描述性消息提交：
|
||
```bash
|
||
git commit -m "feat: implement <模块名> module
|
||
|
||
- Add RPCD backend with methods: status, get_*, set_*
|
||
- Create views for overview, settings, etc.
|
||
- Configure ACL permissions
|
||
- Add menu entries
|
||
|
||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||
|
||
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
|
||
```
|
||
|
||
- [ ] 推送（验证自动运行）：
|
||
```bash
|
||
git push
|
||
```
|
||
|
||
## 常见验证错误及修复
|
||
|
||
### 错误：RPCD 脚本名称与 ubus 对象不匹配
|
||
|
||
```
|
||
✗ ERROR: luci-app-cdn-cache: RPCD script 'cdn-cache' does NOT match ubus object 'luci.cdn-cache'
|
||
```
|
||
|
||
**修复：**
|
||
```bash
|
||
cd luci-app-cdn-cache/root/usr/libexec/rpcd
|
||
mv cdn-cache luci.cdn-cache
|
||
```
|
||
|
||
### 错误：菜单路径 → 文件未找到
|
||
|
||
```
|
||
✗ ERROR: luci-app-netifyd: Menu path 'netifyd/overview' → file NOT FOUND
|
||
Expected: htdocs/luci-static/resources/view/netifyd/overview.js
|
||
```
|
||
|
||
**修复选项 1：** 更新菜单路径以匹配文件：
|
||
```bash
|
||
# 编辑 root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json
|
||
# 更改："path": "netifyd/overview"
|
||
# 为： "path": "netifyd-dashboard/overview"
|
||
```
|
||
|
||
**修复选项 2：** 移动视图文件以匹配菜单：
|
||
```bash
|
||
mv htdocs/luci-static/resources/view/netifyd-dashboard \
|
||
htdocs/luci-static/resources/view/netifyd
|
||
```
|
||
|
||
### 错误：RPCD 脚本不可执行
|
||
|
||
```
|
||
✗ ERROR: luci-app-cdn-cache: luci.cdn-cache is NOT executable
|
||
```
|
||
|
||
**修复：**
|
||
```bash
|
||
chmod +x luci-app-cdn-cache/root/usr/libexec/rpcd/luci.cdn-cache
|
||
```
|
||
|
||
### 错误：RPCD 中的方法 'get_stats' 未在 ACL 中找到
|
||
|
||
```
|
||
⚠ WARNING: luci-app-cdn-cache: Method 'get_stats' from RPCD not in ACL
|
||
```
|
||
|
||
**修复：**
|
||
```bash
|
||
# 编辑 root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json
|
||
# 将 'get_stats' 添加到 read.ubus 数组：
|
||
{
|
||
"luci-app-cdn-cache": {
|
||
"read": {
|
||
"ubus": {
|
||
"luci.cdn-cache": ["status", "get_config", "get_stats"]
|
||
↑ 在此添加
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误：无效的 JSON 语法
|
||
|
||
```
|
||
✗ ERROR: luci-app-cdn-cache: acl.d JSON is INVALID - syntax error
|
||
```
|
||
|
||
**修复：**
|
||
```bash
|
||
# 验证 JSON：
|
||
python3 -m json.tool root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json
|
||
|
||
# 常见问题：
|
||
# - 数组元素之间缺少逗号
|
||
# - 最后一个元素后有尾随逗号
|
||
# - 字符串中有未转义的引号
|
||
```
|
||
|
||
## 绕过验证（不推荐）
|
||
|
||
在极少数情况下，您可能需要绕过验证：
|
||
|
||
```bash
|
||
# 跳过推送前验证：
|
||
git push --no-verify
|
||
|
||
# 跳过模块生成验证：
|
||
# （无法绕过 - 仅供参考）
|
||
```
|
||
|
||
**⚠️ 警告：** 绕过验证可能导致生产环境中的模块损坏！
|
||
|
||
## 与 CI/CD 集成
|
||
|
||
### GitHub Actions
|
||
|
||
将验证添加到您的工作流：
|
||
|
||
```yaml
|
||
name: Validate Modules
|
||
|
||
on: [push, pull_request]
|
||
|
||
jobs:
|
||
validate:
|
||
runs-on: ubuntu-latest
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Install dependencies
|
||
run: |
|
||
sudo apt-get update
|
||
sudo apt-get install -y python3 shellcheck
|
||
|
||
- name: Run module validation
|
||
run: |
|
||
chmod +x secubox-tools/validate-modules.sh
|
||
./secubox-tools/validate-modules.sh
|
||
|
||
- name: Run pre-push validation
|
||
run: |
|
||
chmod +x secubox-tools/pre-push-validation.sh
|
||
./secubox-tools/pre-push-validation.sh
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **提交前始终验证**
|
||
```bash
|
||
./secubox-tools/validate-module-generation.sh luci-app-<模块>
|
||
```
|
||
|
||
2. **安装 git hooks 以实现自动验证**
|
||
```bash
|
||
./secubox-tools/install-git-hooks.sh
|
||
```
|
||
|
||
3. **立即修复错误** - 不要累积验证债务
|
||
|
||
4. **查看警告** - 它们通常表示真正的问题
|
||
|
||
5. **在 OpenWrt 上测试** 后再标记为完成：
|
||
```bash
|
||
scp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/
|
||
ssh root@192.168.1.1
|
||
opkg install /tmp/luci-app-*.ipk
|
||
/etc/init.d/rpcd restart
|
||
/etc/init.d/uhttpd restart
|
||
```
|
||
|
||
6. **在模块 README 中记录模块特定要求**
|
||
|
||
## 故障排除
|
||
|
||
### 验证脚本无法运行
|
||
|
||
```bash
|
||
# 确保脚本可执行：
|
||
chmod +x secubox-tools/*.sh
|
||
|
||
# 检查依赖项：
|
||
which python3 # 用于 JSON 验证
|
||
which shellcheck # 用于 shell 脚本验证
|
||
```
|
||
|
||
### Git hook 不运行
|
||
|
||
```bash
|
||
# 检查 hook 是否已安装：
|
||
ls -la .git/hooks/pre-push
|
||
|
||
# 重新安装 hooks：
|
||
./secubox-tools/install-git-hooks.sh
|
||
```
|
||
|
||
### 验证中的误报
|
||
|
||
如果验证错误地报告错误，请报告：
|
||
- 创建包含完整验证输出的 issue
|
||
- 包括模块名称和失败的特定检查
|
||
- 我们将更新验证逻辑
|
||
|
||
## 其他资源
|
||
|
||
- [CLAUDE.md](claude.md) - 主要项目文档
|
||
- [secubox-tools/README.md](https://github.com/CyberMind-FR/secubox-openwrt/blob/master/secubox-tools/README.md) - 工具文档
|
||
- [Feature Regeneration Prompts](feature-regeneration-prompts.md) - 模块生成提示
|
||
|
||
## 支持
|
||
|
||
如果您遇到验证问题：
|
||
|
||
1. 检查本指南中的常见错误
|
||
2. 使用详细输出运行验证
|
||
3. 查看 CLAUDE.md 了解命名约定
|
||
4. 在 GitHub 上创建包含验证输出的 issue
|