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>
556 lines
16 KiB
Markdown
556 lines
16 KiB
Markdown
# CLAUDE.md
|
||
|
||
> **语言:** [English](../docs/claude.md) | [Francais](../docs-fr/claude.md) | 中文
|
||
|
||
**版本:** 1.0.0
|
||
**最后更新:** 2025-12-28
|
||
**状态:** 活跃
|
||
|
||
本文件为 Claude Code (claude.ai/code) 提供处理本仓库代码的指导说明。
|
||
|
||
## 文档索引
|
||
|
||
**重要:** 在处理任何代码之前，请查阅以下指南:
|
||
|
||
1. **[DEVELOPMENT-GUIDELINES.md](development-guidelines.md)** - **完整指南**
|
||
- 设计系统与UI指南（调色板、排版、组件）
|
||
- 架构与命名规范（RPCD、菜单路径、前缀）
|
||
- RPCD与ubus最佳实践（常见错误、解决方案）
|
||
- ACL与权限（模板、验证）
|
||
- JavaScript模式（API模块、视图、事件处理）
|
||
- CSS/样式标准（变量、响应式、深色模式）
|
||
- 常见错误与解决方案（诊断、修复）
|
||
- 验证清单（提交前、部署前、部署后）
|
||
- 部署流程（脚本、回滚、版本控制）
|
||
|
||
2. **[QUICK-START.md](quick-start.md)** - **快速参考**
|
||
- 关键规则（RPCD命名、菜单路径、权限）
|
||
- 设计系统要点（颜色、字体、类）
|
||
- 常用命令（验证、构建、部署、调试）
|
||
- 快速代码模板（RPCD、View、Headers、Cards）
|
||
- 快速错误修复
|
||
|
||
3. **CLAUDE.md**（本文件） - **架构与构建**
|
||
- 构建命令（OpenWrt SDK、本地构建）
|
||
- 模块结构（文件、目录）
|
||
- CI/CD工作流
|
||
- 常见技术问题
|
||
|
||
**必须始终遵守的关键规则:**
|
||
|
||
1. **RPCD脚本命名:** 文件名 = ubus对象名（`luci.system-hub`）
|
||
2. **菜单路径匹配:** 菜单路径 = 视图文件路径（`system-hub/overview.js`）
|
||
3. **权限:** RPCD = 755, CSS/JS = 644
|
||
- **自动修复:** `./secubox-tools/fix-permissions.sh --local`（提交前）
|
||
- **远程自动修复:** `./secubox-tools/fix-permissions.sh --remote`（部署后）
|
||
4. **验证:** 提交前始终执行 `./secubox-tools/validate-modules.sh`
|
||
- **7项自动检查:** RPCD命名、菜单路径、视图文件、RPCD权限、JSON语法、ubus命名、**htdocs权限**
|
||
5. **CSS变量:** 始终使用 `var(--sh-*)`，切勿硬编码颜色
|
||
6. **深色模式:** 始终使用 `[data-theme="dark"]` 支持深色模式
|
||
7. **排版:** Inter（文本）、JetBrains Mono（数值）
|
||
8. **渐变效果:** 使用 `--sh-primary` 到 `--sh-primary-end` 实现渐变
|
||
|
||
## 项目概述
|
||
|
||
SecuBox是一套面向OpenWrt的综合安全与网络管理套件。本仓库包含13个LuCI应用包，提供安全监控、网络智能、访问控制、带宽管理和系统管理的仪表板。
|
||
|
||
## 构建命令
|
||
|
||
### OpenWrt SDK构建
|
||
|
||
```bash
|
||
# 构建单个软件包
|
||
make package/luci-app-<模块名>/compile V=s
|
||
|
||
# 清理后重新构建软件包
|
||
make package/luci-app-<模块名>/clean
|
||
make package/luci-app-<模块名>/compile V=s
|
||
|
||
# 将软件包安装到暂存目录
|
||
make package/luci-app-<模块名>/install
|
||
```
|
||
|
||
### 测试软件包
|
||
|
||
```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
|
||
```
|
||
|
||
### 验证
|
||
|
||
```bash
|
||
# 首先修复文件权限（关键）
|
||
./secubox-tools/fix-permissions.sh --local
|
||
|
||
# 运行全面的模块验证（推荐 - 7项检查）
|
||
./secubox-tools/validate-modules.sh
|
||
# 检查项:
|
||
# 1. RPCD脚本名与ubus对象名
|
||
# 2. 菜单路径与视图文件位置
|
||
# 3. 视图文件有菜单入口
|
||
# 4. RPCD脚本权限（755）
|
||
# 5. JSON语法验证
|
||
# 6. ubus对象命名规范
|
||
# 7. htdocs文件权限（CSS/JS为644）
|
||
|
||
# 验证shell脚本（RPCD后端）
|
||
shellcheck luci-app-*/root/usr/libexec/rpcd/*
|
||
|
||
# 验证JSON文件
|
||
find . -name "*.json" -exec jsonlint {} \;
|
||
|
||
# 运行自动修复工具
|
||
./secubox-tools/secubox-repair.sh
|
||
|
||
# 修复已部署路由器上的权限
|
||
./secubox-tools/fix-permissions.sh --remote
|
||
|
||
# 运行诊断
|
||
./secubox-tools/secubox-debug.sh luci-app-<模块名>
|
||
```
|
||
|
||
### 本地构建（复制GitHub Actions）
|
||
|
||
`local-build.sh`脚本允许您在本地构建和测试软件包，复制GitHub Actions工作流:
|
||
|
||
```bash
|
||
# 验证所有软件包（语法、JSON、shell脚本）
|
||
./secubox-tools/local-build.sh validate
|
||
|
||
# 为x86_64构建所有软件包
|
||
./secubox-tools/local-build.sh build
|
||
|
||
# 构建单个软件包
|
||
./secubox-tools/local-build.sh build luci-app-system-hub
|
||
|
||
# 为特定架构构建
|
||
./secubox-tools/local-build.sh build --arch aarch64-cortex-a72
|
||
|
||
# 完整验证 + 构建
|
||
./secubox-tools/local-build.sh full
|
||
|
||
# 清理构建产物
|
||
./secubox-tools/local-build.sh clean
|
||
```
|
||
|
||
支持的架构:
|
||
- `x86-64` - PC、虚拟机（默认）
|
||
- `aarch64-cortex-a53` - ARM Cortex-A53 (ESPRESSObin)
|
||
- `aarch64-cortex-a72` - ARM Cortex-A72 (MOCHAbin, RPi4)
|
||
- `aarch64-generic` - 通用ARM64
|
||
- `mips-24kc` - MIPS 24Kc (TP-Link)
|
||
- `mipsel-24kc` - MIPS LE (Xiaomi, GL.iNet)
|
||
|
||
脚本自动:
|
||
- 下载并缓存OpenWrt SDK
|
||
- 配置feeds（packages、luci），使用正确的版本分支
|
||
- 将您的软件包复制到SDK
|
||
- 构建软件包（25.12+为.apk，旧版本为.ipk）
|
||
- 将产物收集到`build/<架构>/`
|
||
|
||
**软件包格式支持:**
|
||
- OpenWrt 25.12+和SNAPSHOT: `.apk`格式（基于Alpine的新包管理器）
|
||
- OpenWrt 24.10及更早版本: `.ipk`格式（opkg包管理器）
|
||
|
||
环境变量:
|
||
- `OPENWRT_VERSION` - OpenWrt版本（默认: 24.10.5，也支持: 25.12.0-rc1、23.05.5、SNAPSHOT）
|
||
- `SDK_DIR` - SDK目录（默认: ./sdk）
|
||
- `BUILD_DIR` - 构建输出目录（默认: ./build）
|
||
- `CACHE_DIR` - 下载缓存目录（默认: ./cache）
|
||
|
||
## 架构
|
||
|
||
### LuCI软件包结构
|
||
|
||
所有SecuBox模块遵循标准的LuCI应用结构:
|
||
|
||
```
|
||
luci-app-<模块名>/
|
||
├── Makefile # OpenWrt软件包定义
|
||
├── README.md # 模块文档
|
||
├── htdocs/luci-static/resources/
|
||
│ ├── view/<模块名>/ # JavaScript UI视图
|
||
│ │ ├── overview.js # 主仪表板视图
|
||
│ │ └── *.js # 其他视图
|
||
│ └── <模块名>/
|
||
│ ├── api.js # RPC API客户端模块
|
||
│ └── dashboard.css # 模块特定样式
|
||
└── root/
|
||
├── etc/config/<模块名> # UCI配置（可选）
|
||
└── usr/
|
||
├── libexec/rpcd/
|
||
│ └── luci.<模块名> # RPCD后端脚本（必须使用luci.前缀！）
|
||
└── share/
|
||
├── luci/menu.d/ # 菜单JSON定义
|
||
│ └── luci-app-<模块名>.json
|
||
└── rpcd/acl.d/ # ACL权限JSON
|
||
└── luci-app-<模块名>.json
|
||
```
|
||
|
||
### 前后端通信
|
||
|
||
1. **前端（JavaScript）**: 位于`htdocs/luci-static/resources/`
|
||
- 视图使用LuCI的`form`和`view`类
|
||
- 通过`api.js`模块使用`L.resolveDefault()`进行API调用
|
||
- 来自`ui.js`的UI组件（Dropdown、Checkbox、Combobox等）
|
||
|
||
2. **后端（RPCD）**: 位于`root/usr/libexec/rpcd/`
|
||
- 实现RPC方法的shell脚本
|
||
- 必须向stdout输出JSON
|
||
- 方法通过ubus调用: `ubus call <模块> <方法>`
|
||
|
||
3. **菜单定义**: `root/usr/share/luci/menu.d/luci-app-<模块>.json`
|
||
- 定义菜单结构和导航
|
||
- 指定视图路径和依赖
|
||
|
||
4. **ACL定义**: `root/usr/share/rpcd/acl.d/luci-app-<模块>.json`
|
||
- 定义ubus方法的访问控制
|
||
- 将读/写权限映射到用户组
|
||
|
||
### 关键命名规范
|
||
|
||
**重要**: 以下命名规则是模块正常工作的**强制要求**:
|
||
|
||
#### 1. RPCD脚本必须匹配ubus对象名
|
||
|
||
RPCD脚本文件名必须与JavaScript中使用的ubus对象名完全匹配:
|
||
|
||
```javascript
|
||
// 在JavaScript中（htdocs/luci-static/resources/view/*/）:
|
||
var callStatus = rpc.declare({
|
||
object: 'luci.cdn-cache', // <- 这个对象名
|
||
method: 'status'
|
||
});
|
||
```
|
||
|
||
```bash
|
||
# RPCD脚本文件名必须匹配:
|
||
root/usr/libexec/rpcd/luci.cdn-cache # <- 必须正好是'luci.cdn-cache'
|
||
```
|
||
|
||
**常见错误**: 如果名称不匹配，您会收到:
|
||
- `RPC call to luci.cdn-cache/status failed with error -32000: Object not found`
|
||
- `Command failed: Method not found`
|
||
|
||
**解决方案**: 所有RPCD脚本必须使用`luci.`前缀:
|
||
- 正确: `luci.cdn-cache`、`luci.system-hub`、`luci.wireguard-dashboard`
|
||
- 错误: `cdn-cache`、`system-hub`、`wireguard-dashboard`
|
||
|
||
#### 2. 菜单路径必须匹配视图文件位置
|
||
|
||
菜单JSON中的路径条目必须与实际的视图文件对应:
|
||
|
||
```json
|
||
// 在menu.d/luci-app-netifyd-dashboard.json中:
|
||
{
|
||
"action": {
|
||
"type": "view",
|
||
"path": "netifyd-dashboard/overview" // <- 必须匹配文件位置
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
# 视图文件必须存在于:
|
||
htdocs/luci-static/resources/view/netifyd-dashboard/overview.js
|
||
# ↑ 与菜单相同的路径 ↑
|
||
```
|
||
|
||
**常见错误**: 如果路径不匹配:
|
||
- `HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'`
|
||
|
||
**解决方案**: 确保菜单路径与目录结构匹配:
|
||
- 正确: 菜单路径`netifyd-dashboard/overview` -> 文件`view/netifyd-dashboard/overview.js`
|
||
- 错误: 菜单路径`netifyd/overview` -> 文件`view/netifyd-dashboard/overview.js`
|
||
|
||
#### 3. ubus对象命名规范
|
||
|
||
所有ubus对象必须以`luci.`前缀开头:
|
||
|
||
```javascript
|
||
// 正确:
|
||
object: 'luci.cdn-cache'
|
||
object: 'luci.system-hub'
|
||
object: 'luci.wireguard-dashboard'
|
||
|
||
// 错误:
|
||
object: 'cdn-cache'
|
||
object: 'systemhub'
|
||
```
|
||
|
||
#### 4. 部署前验证
|
||
|
||
部署前**始终**运行验证:
|
||
|
||
```bash
|
||
./secubox-tools/validate-modules.sh
|
||
```
|
||
|
||
此脚本检查:
|
||
- RPCD脚本名与ubus对象匹配
|
||
- 菜单路径与视图文件位置匹配
|
||
- 视图文件有对应的菜单入口
|
||
- RPCD脚本可执行
|
||
- JSON文件语法有效
|
||
- ubus对象遵循命名规范
|
||
|
||
### Makefile结构
|
||
|
||
每个软件包的Makefile必须定义:
|
||
- `PKG_NAME`: 软件包名（必须与目录匹配）
|
||
- `PKG_VERSION`: 版本号
|
||
- `PKG_RELEASE`: 软件包发布号
|
||
- `LUCI_TITLE`: LuCI中显示的标题
|
||
- `LUCI_DEPENDS`: 软件包依赖（例如`+luci-base +rpcd`）
|
||
- `LUCI_DESCRIPTION`: 简短描述
|
||
- `PKG_MAINTAINER`: 维护者姓名和邮箱
|
||
- `PKG_LICENSE`: 许可证（通常为Apache-2.0）
|
||
|
||
Makefile包含LuCI构建系统的`luci.mk`，用于处理安装。
|
||
|
||
## 常见开发模式
|
||
|
||
### 创建新模块
|
||
|
||
1. 复制模板: `cp -r templates/luci-app-template luci-app-新模块`
|
||
2. 更新Makefile中的PKG_NAME、LUCI_TITLE等
|
||
3. 在`htdocs/`和`root/`下创建目录结构
|
||
4. 用shell实现RPCD后端
|
||
5. 创建JavaScript视图
|
||
6. 定义菜单和ACL的JSON文件
|
||
|
||
### RPCD后端模式
|
||
|
||
RPCD后端是shell脚本，它们:
|
||
- 解析`$1`获取方法名
|
||
- 使用`printf`或`echo`输出有效的JSON
|
||
- 使用`case`语句进行方法路由
|
||
- 如需要则加载UCI配置: `. /lib/functions.sh`
|
||
|
||
示例:
|
||
```bash
|
||
#!/bin/sh
|
||
case "$1" in
|
||
list)
|
||
echo '{ "status": {}, "stats": {} }'
|
||
;;
|
||
call)
|
||
case "$2" in
|
||
status)
|
||
# 输出JSON
|
||
printf '{"running": true, "version": "1.0.0"}\n'
|
||
;;
|
||
esac
|
||
;;
|
||
esac
|
||
```
|
||
|
||
### JavaScript视图模式
|
||
|
||
视图扩展`L.view`并实现`load()`和`render()`:
|
||
|
||
```javascript
|
||
'use strict';
|
||
'require view';
|
||
'require form';
|
||
'require <模块>/api as API';
|
||
|
||
return L.view.extend({
|
||
load: function() {
|
||
return Promise.all([
|
||
API.getStatus(),
|
||
API.getStats()
|
||
]);
|
||
},
|
||
|
||
render: function(data) {
|
||
var m, s, o;
|
||
m = new form.Map('config', _('标题'));
|
||
s = m.section(form.TypedSection, 'section');
|
||
// 添加表单字段...
|
||
return m.render();
|
||
}
|
||
});
|
||
```
|
||
|
||
## 模块分类
|
||
|
||
1. **核心控制**（2个模块）
|
||
- luci-app-secubox: 中央控制台
|
||
- luci-app-system-hub: 系统控制中心
|
||
|
||
2. **安全与监控**（2个模块）
|
||
- luci-app-crowdsec-dashboard: CrowdSec安全
|
||
- luci-app-netdata-dashboard: 系统监控
|
||
|
||
3. **网络智能**（2个模块）
|
||
- luci-app-netifyd-dashboard: 深度包检测
|
||
- luci-app-network-modes: 网络模式配置
|
||
|
||
4. **VPN与访问控制**（3个模块）
|
||
- luci-app-wireguard-dashboard: WireGuard VPN
|
||
- luci-app-client-guardian: NAC与强制门户
|
||
- luci-app-auth-guardian: 认证系统
|
||
|
||
5. **带宽与流量**（2个模块）
|
||
- luci-app-bandwidth-manager: QoS与配额
|
||
- luci-app-media-flow: 媒体流量检测
|
||
|
||
6. **性能与服务**（2个模块）
|
||
- luci-app-cdn-cache: CDN代理缓存
|
||
- luci-app-vhost-manager: 虚拟主机管理器
|
||
|
||
## CI/CD集成
|
||
|
||
### GitHub Actions工作流
|
||
|
||
1. **build-openwrt-packages.yml**: 为所有架构编译软件包
|
||
- 在push、PR和tag时触发
|
||
- 13种架构的矩阵构建
|
||
- 按架构上传产物
|
||
|
||
2. **build-secubox-images.yml**: 构建自定义OpenWrt镜像
|
||
- 创建预装SecuBox的完整固件镜像
|
||
|
||
3. **test-validate.yml**: 验证和测试
|
||
- 验证Makefile结构
|
||
- 检查JSON语法
|
||
- 对脚本运行shellcheck
|
||
- 验证文件权限
|
||
|
||
### 支持的架构
|
||
|
||
ARM64: aarch64-cortex-a53、aarch64-cortex-a72、aarch64-generic、mediatek-filogic、rockchip-armv8、bcm27xx-bcm2711
|
||
|
||
ARM32: arm-cortex-a7-neon、arm-cortex-a9-neon、qualcomm-ipq40xx、qualcomm-ipq806x
|
||
|
||
MIPS: mips-24kc、mipsel-24kc、mipsel-74kc
|
||
|
||
x86: x86-64、x86-generic
|
||
|
||
## 关键文件和目录
|
||
|
||
- `makefiles/`: 模块的参考Makefile（备份/模板）
|
||
- `secubox-tools/`: 修复和调试工具
|
||
- `secubox-repair.sh`: 自动修复Makefile和RPCD问题
|
||
- `secubox-debug.sh`: 验证软件包结构
|
||
- `templates/`: 用于创建新模块的软件包模板
|
||
- `.github/workflows/`: CI/CD自动化脚本
|
||
|
||
## 常见问题与解决方案
|
||
|
||
### RPC错误: "Object not found"或"Method not found"
|
||
|
||
**错误**: `RPC call to luci.cdn-cache/status failed with error -32000: Object not found`
|
||
|
||
**原因**: RPCD脚本名与JavaScript中的ubus对象名不匹配
|
||
|
||
**解决方案**:
|
||
1. 检查JavaScript文件中的ubus对象名:
|
||
```bash
|
||
grep -r "object:" luci-app-*/htdocs --include="*.js"
|
||
```
|
||
2. 重命名RPCD脚本使其完全匹配（包括`luci.`前缀）:
|
||
```bash
|
||
mv root/usr/libexec/rpcd/cdn-cache root/usr/libexec/rpcd/luci.cdn-cache
|
||
```
|
||
3. 在路由器上重启RPCD:
|
||
```bash
|
||
/etc/init.d/rpcd restart
|
||
```
|
||
|
||
### HTTP 404错误: 视图文件未找到
|
||
|
||
**错误**: `HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'`
|
||
|
||
**原因**: 菜单路径与实际的视图文件位置不匹配
|
||
|
||
**解决方案**:
|
||
1. 检查菜单JSON中的路径:
|
||
```bash
|
||
grep '"path":' root/usr/share/luci/menu.d/*.json
|
||
```
|
||
2. 验证视图文件存在于匹配的位置:
|
||
```bash
|
||
ls htdocs/luci-static/resources/view/
|
||
```
|
||
3. 更新菜单路径以匹配文件位置，或移动文件以匹配菜单路径
|
||
|
||
### RPCD无响应
|
||
|
||
安装/更新软件包后:
|
||
```bash
|
||
/etc/init.d/rpcd restart
|
||
/etc/init.d/uhttpd restart
|
||
```
|
||
|
||
### 菜单不显示
|
||
|
||
检查:
|
||
1. 菜单JSON有效: `jsonlint root/usr/share/luci/menu.d/*.json`
|
||
2. ACL授予访问权限: 检查`root/usr/share/rpcd/acl.d/*.json`
|
||
3. 依赖已安装: 检查Makefile中的`LUCI_DEPENDS`
|
||
4. 菜单路径与视图文件位置匹配（见上文）
|
||
|
||
### 构建失败
|
||
|
||
常见原因:
|
||
1. Makefile中缺少字段（PKG_NAME、LUCI_TITLE等）
|
||
2. menu.d或acl.d中的JSON语法无效
|
||
3. RPCD脚本不可执行（需要chmod +x）
|
||
4. 包含路径错误（应为`include ../../luci.mk`）
|
||
5. RPCD脚本名与ubus对象不匹配（必须使用`luci.`前缀）
|
||
|
||
使用修复工具: `./secubox-tools/secubox-repair.sh`
|
||
|
||
### 快速诊断
|
||
|
||
运行验证脚本检查所有命名规范:
|
||
```bash
|
||
./secubox-tools/validate-modules.sh
|
||
```
|
||
|
||
## 开发工作流
|
||
|
||
1. 修改模块文件
|
||
2. **运行验证检查**（关键）:
|
||
```bash
|
||
./secubox-tools/validate-modules.sh
|
||
# 或使用本地构建工具:
|
||
./secubox-tools/local-build.sh validate
|
||
```
|
||
3. 测试JSON语法: `jsonlint <文件>.json`
|
||
4. 测试shell脚本: `shellcheck <脚本>`
|
||
5. 本地构建和测试软件包（推荐）:
|
||
```bash
|
||
# 构建单个软件包
|
||
./secubox-tools/local-build.sh build luci-app-<名称>
|
||
|
||
# 或使用手动SDK构建:
|
||
make package/luci-app-<名称>/compile V=s
|
||
```
|
||
6. 在测试路由器上安装并验证功能
|
||
7. 如需要运行修复工具: `./secubox-tools/secubox-repair.sh`
|
||
8. 提交更改并推送（触发CI验证）
|
||
9. 为发布创建标签: `git tag -a v1.0.0 -m "Release 1.0.0"`
|
||
|
||
## 重要说明
|
||
|
||
- **关键**: RPCD脚本名必须与ubus对象名匹配（使用`luci.`前缀）
|
||
- **关键**: 菜单路径必须与视图文件目录结构匹配
|
||
- **关键**: 提交前始终运行`./secubox-tools/validate-modules.sh`
|
||
- 所有模块使用Apache-2.0许可证
|
||
- RPCD后端必须可执行（chmod +x）
|
||
- JavaScript文件使用严格模式: `'use strict';`
|
||
- 菜单入口需要正确的依赖链
|
||
- ACL必须授予ubus call和luci-cgi访问权限
|
||
- UCI配置文件是可选的（许多模块不需要）
|
||
- 所有软件包构建为架构`all`（无编译代码）
|