chore: 导入旧记忆备份供恢复

2026-09-23 22:38:40 +08:00
parent 5313fcee7a
commit 6a6a895eaf
638 changed files with 29816 additions and 1 deletions
@@ -0,0 +1,105 @@
+---
+title: Common Issues & Remedies
+type: curated
+permalink: main/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/common-issues-remedies
+stable_id: b74934b7-77c3-4cbc-acd6-f6f7d8dc350e
+scope: project
+project_id: 4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: troubleshooting
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_git_commits:
+- de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 188
+source_revisions: {}
+source_dispositions:
+  processed: 188
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:backend/src/handlers.rs
+- git:backend/src/dbus.rs
+- git:backend/src/iptables.rs
+- git:backend/src/usb_switch.rs
+job_cited_source_ids:
+- git:backend/src/handlers.rs
+- git:backend/src/dbus.rs
+- git:backend/src/iptables.rs
+- git:backend/src/usb_switch.rs
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 87
+source_hash: 96f0e4026558c8a03161f53b392fcec7359d4d701c4f33576b44e2f308b0ec5a
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: a9f69899-ee39-4900-b39a-a54d737f9614
+created_at: '2026-08-19T18:49:42.050675+00:00'
+updated_at: '2026-08-19T18:49:42.051299+00:00'
+tags:
+- troubleshooting
+- issues
+- solutions
+---
+
+## 1. Concurrent AT / DBus Commands → `org.ofono.Error.InProgress`
+- **Cause**: Overlapping AT commands sent to ofono.
+- **Solution**: Use the global serial lock (`with_serial`) provided in `backend/src/serial.rs`. All AT‑related paths in `dbus.rs` and `handlers.rs` already wrap calls with this lock.
+- **Reference**: `git:backend/src/dbus.rs`.
+
+## 2. Stale iptables Rules After Crash
+- **Cause**: Crash leaves NAT/iptables rules active.
+- **Solution**: `iptables_watchdog` (started after a 5 s delay) periodically flushes iptables. Ensure `flush_iptables()` is invoked before any data‑connection change.
+- **Reference**: `git:backend/src/iptables.rs`.
+
+## 3. OTA Package Corruption
+- **Cause**: Missing files, wrong architecture, or checksum mismatch.
+- **Solution**: Run `validate_ota_package()` (in `backend/src/ota.rs`) before install. The CI pipeline also validates checksums via `scripts/pack-ota.sh`.
+- **Reference**: `memory:e92dbe0b…`.
+
+## 4. Missing Authentication on AT Gateway
+- **Cause**: `/api/at` endpoint is unauthenticated.
+- **Remedy**: Implement token‑based auth or whitelist allowed AT commands.
+- **Reference**: `git:backend/src/handlers.rs` (open issue).
+
+## 5. Sensitive Fields Redacted
+- **Cause**: APN passwords, FRPC tokens stored as `[REDACTED]`.
+- **Remedy**: Integrate secure storage (Vaultwarden or encrypted file) and expose UI controls for entry.
+- **Reference**: `git:backend/src/config.rs`, `git:frontend/src/pages/Network.tsx`.
+
+## 6. USB Hot‑Switch Instability
+- **Cause**: Re‑configuring configfs gadget may fail, leaving the device without USB networking.
+- **Remedy**: Use the `switch_usb_mode_advanced` routine; if it fails, fallback to a reboot. Mark the UI option as experimental.
+- **Reference**: `git:backend/src/usb_switch.rs`.
+
+## 7. Band‑Mask Mismatch
+- **Cause**: UI allows bands unsupported by hardware; backend rejects silently.
+- **Remedy**: Capture the backend error response and display it in the UI; validate band selections before sending.
+- **Reference**: `git:frontend/src/pages/Network.tsx`.
+
+## 8. FRPC Log Growth
+- **Cause**: Logs grow beyond 512 KB without rotation.
+- **Remedy**: Adjust `log_rotation_size` in `state.rs` or enable compression.
+- **Reference**: `git:backend/src/state.rs`.
+
+## 9. CORS Wide Open
+- **Cause**: Development CORS set to `*`.
+- **Remedy**: Restrict allowed origins in production (`main.rs`). Add environment‑specific configuration.
+- **Reference**: `git:backend/src/main.rs`.
+
+## 10. No Unit Tests
+- **Cause**: Repository lacks test suites.
+- **Remedy**: Add Rust unit tests for utilities (`utils.rs`) and Jest/RTL tests for frontend components.
+- **Reference**: Various source files.
+
+*Each troubleshooting entry is traceable to its source ID as indicated.*
@@ -0,0 +1,107 @@
+---
+title: System Architecture Overview (Backend + Frontend)
+type: curated
+permalink: main/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/system-architecture-overview-backend-frontend
+stable_id: faab1e63-b668-4362-896d-9a82ea81d348
+scope: project
+project_id: 4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: architecture
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_git_commits:
+- de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 188
+source_revisions: {}
+source_dispositions:
+  processed: 188
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:backend/Cargo.toml
+- git:frontend/pnpm-lock.yaml
+job_cited_source_ids:
+- git:backend/Cargo.toml
+- git:frontend/pnpm-lock.yaml
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 87
+source_hash: 96f0e4026558c8a03161f53b392fcec7359d4d701c4f33576b44e2f308b0ec5a
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: a9f69899-ee39-4900-b39a-a54d737f9614
+created_at: '2026-08-19T18:49:38.284609+00:00'
+updated_at: '2026-08-19T18:49:38.285207+00:00'
+tags:
+- architecture
+- system‑design
+- backend
+- frontend
+---
+
+## 1. Backend Architecture (Rust)
+
+- **Core Stack**: Rust 2021, Axum 0.8 (HTTP server), Tokio 1.48 (async runtime), `zbus` 5 for DBus communication with **ofono**.
+- **Modules**:
+  - `config.rs` – JSON‑based configuration with hot‑reload; aggregates webhook, SMS‑push, refresh, FRPC sub‑configs.
+  - `db.rs` – Embedded SQLite (`rusqlite`) storing SMS and call history; protected by `Arc<Mutex<Connection>>`.
+  - `dbus.rs` – Generated proxies for ofono interfaces; all calls go through the global serial lock (`with_serial`).
+  - `handlers.rs` – HTTP API handlers exposing health, AT gateway, device info, USB mode, band‑lock, OTA, FRPC, webhook, SMS‑push, etc. All responses use a uniform JSON envelope.
+  - `ota.rs` – Validates and installs OTA packages atomically; checks architecture, version monotonicity and checksums.
+  - `state.rs` – FRPC lifecycle management (install, config render, start/stop, log rotation).
+  - `usb_switch.rs` – Configfs‑based USB gadget re‑configuration; persistent mode stored in `/mnt/data/mode.cfg`.
+  - `utils.rs` – Helpers for band‑mask conversion, system stats, AT response parsing.
+- **Build Process**: Cross‑compiled on a Windows host using Docker (`docker/gnu-builder.Dockerfile`) targeting `aarch64-unknown-linux-gnu`. Build script (`build.rs`) injects `APP_VERSION`, `GIT_BRANCH`, `GIT_COMMIT`.
+- **Docker Image**: Ubuntu 18.04 base with `gcc-aarch64-linux-gnu`; installs Rust toolchain and cross‑compiler.
+
+**Key Design Decisions** (derived from evidence):
+- Global serial lock to avoid `InProgress` DBus errors.
+- iptables watchdog to clean stale NAT rules.
+- All HTTP endpoints currently return `200 OK` (open issue).
+- CORS set to `*` (development convenience, open issue).
+- Sensitive fields are redacted in source code; secure storage is pending.
+
+## 2. Front‑end Architecture (React 19 + TypeScript 5.9)
+
+- **Build Tool**: Vite 7 with alias `@` → `src/*`. Injects compile‑time constants (`__APP_VERSION__`, `__GIT_COMMIT__`).
+- **UI Library**: MUI v7 (Emotion styling engine). Theme persisted via `ThemeContext`.
+- **State / Data Fetching**: `@tanstack/react-query` 5 for caching; custom `useApi` hook wraps `fetch` with timeout and error mapping.
+- **Global Contexts**: `ThemeContext` (light/dark), `RefreshContext` (polling interval). Both persisted in `localStorage`.
+- **Routing**: React Router lazy‑loaded routes for each page (Dashboard, ATConsole, Network, FRP, OTA, etc.).
+- **Pages**:
+  - **Dashboard** – Real‑time status overview, quick controls, system resource monitors.
+  - **ATConsole** – Raw AT command gateway with history.
+  - **Configuration** – Device toggles, USB mode selector, webhook & SMS‑push config.
+  - **Network** – Cell list, band‑lock UI, APN editor, interface list.
+  - **FRP** – FRPC client management (enable, auto‑start, config, logs).
+  - **OTA Update** – OTA upload, validation table, apply/reboot actions.
+  - **InitScript** – Edit and static‑analyse `init.sh`.
+  - **Phone**, **SMS**, **Terminal**, … (additional functional pages).
+- **Styling Guidelines**: Compact “label‑left / control‑right” for narrow fields; vertical layout for large sections; fixed header with inner scrolling.
+- **Testing & Linting**: ESLint 9, strict TypeScript `strict` mode; no unit tests currently (open issue).
+
+**Key Design Decisions** (frontend):
+- Adaptive polling (`useAdaptivePolling`) scales interval by page visibility.
+- Sensitive identifiers are blurred by default and togglable.
+- All scripts must run on Windows (development platform).
+- UI strings are Chinese‑language by default (communication language set in project metadata).
+
+## 3. Build & Deployment
+
+- `scripts/build.sh` – Cross‑compiles backend, builds frontend via Vite, optionally compresses with UPX, generates OTA meta.
+- `scripts/pack-ota.sh` – Packages binaries, frontend `dist`, FRPC binary; creates `meta.json` with MD5/SHA‑256 checksums.
+- CI (`.github/workflows/build-ota.yml`) runs the above, validates checksums, uploads artifacts.
+- `scripts/deploy.sh` – Pushes OTA artifacts to device via ADB, stops running service, copies files.
+- Docker image (`docker/gnu-builder.Dockerfile`) provides reproducible cross‑compile environment.
+
+**Source IDs**: `git:backend/Cargo.toml`, `git:frontend/pnpm-lock.yaml`, `docker/gnu-builder.Dockerfile`.
@@ -0,0 +1,88 @@
+---
+title: 项目 CPE 运行与维护手册
+type: curated
+permalink: main/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/项目-cpe-运行与维护手册
+stable_id: 9d1ffd0c-9758-495f-ab5f-20e2ebff3034
+scope: project
+project_id: 4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: maintenance
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_git_commits:
+- de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 188
+source_revisions: {}
+source_dispositions:
+  processed: 188
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:backend/src/config.rs
+- git:backend/src/usb_switch.rs
+- git:backend/src/handlers.rs
+- git:frontend/src/pages/ATConsole.tsx
+- git:frontend/src/pages/Configuration.tsx
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+job_cited_source_ids:
+- git:backend/src/config.rs
+- git:backend/src/usb_switch.rs
+- git:backend/src/handlers.rs
+- git:frontend/src/pages/ATConsole.tsx
+- git:frontend/src/pages/Configuration.tsx
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 87
+source_hash: 96f0e4026558c8a03161f53b392fcec7359d4d701c4f33576b44e2f308b0ec5a
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: a9f69899-ee39-4900-b39a-a54d737f9614
+created_at: '2026-08-19T18:49:47.691587+00:00'
+updated_at: '2026-08-19T18:49:47.692127+00:00'
+tags:
+- 运行
+- 维护
+- 故障排查
+- 安全
+- 配置
+---
+
+# 项目 CPE 运行与维护手册
+
+## 组件概览
+- 后端服务 (Rust + Axum) 监听 `0.0.0.0:3000`
+- 前端 (React + Vite) 位于 `/home/root/www/`
+- 可选 FRPC 客户端 `frpc`，配置文件 `frpc.toml`
+- USB Gadget 切换实现于 `backend/src/usb_switch.rs`
+- OTA 更新通过 `scripts/pack-ota.sh` 生成的包，由后端 `ota.rs` 校验并原子替换。
+
+## 配置管理
+- 主配置 `config.json` 支持热重载，涉及 `WebhookConfig`、`SmsPushConfig`、`RefreshConfig`、`FrpcConfig`、`AppConfig`（见 `backend/src/config.rs`）。
+- 敏感信息应通过 Vaultwarden 或加密文件注入，前端 UI 仅显示占位。
+
+## 常规运维任务
+- **日志**: 后端通过 `tracing` 输出，容器可 `docker logs`；FRPC 日志轮转 512 KB。
+- **系统资源**: Dashboard 实时展示 CPU、内存、磁盘、网络、温度、运行时间。
+- **OTA 更新流程**: 上传 `.tar.gz` → 后端 `validate_ota_package()` 检查版本、架构、校验和 → 原子 `rename` 完成更新。
+- **USB 切换**: UI 调用 `switch_usb_mode_advanced`，在 `/mnt/data/mode.cfg` 写入模式并重新启用 UDC。
+
+## 未决事项
+1. OTA 包签名校验与回滚机制（A/B 分区）。
+2. HTTP API token/白名单安全。
+3. 敏感凭证统一 Vaultwarden 管理。
+4. Docker 基础镜像升级至 `ubuntu:24.04`。
+
+**标签**: ["运行","维护","故障排查","安全","配置"]
@@ -0,0 +1,92 @@
+---
+title: 项目 CPE 部署指南
+type: curated
+permalink: main/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/项目-cpe-部署指南
+stable_id: 95f0ac0f-1d2e-4a1a-8adf-4b3638e28035
+scope: project
+project_id: 4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: deployment
+revision: 1
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_git_commits:
+- de28dc8246094e2bc17cab7c764fb4d4a2da71e0
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 188
+source_revisions: {}
+source_dispositions:
+  processed: 188
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:.github/workflows/build-ota.yml
+- git:backend/build.rs
+- git:scripts/build.sh
+- git:scripts/pack-ota.sh
+- git:scripts/deploy.sh
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+job_cited_source_ids:
+- git:.github/workflows/build-ota.yml
+- git:backend/build.rs
+- git:scripts/build.sh
+- git:scripts/pack-ota.sh
+- git:scripts/deploy.sh
+- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
+- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 87
+source_hash: 96f0e4026558c8a03161f53b392fcec7359d4d701c4f33576b44e2f308b0ec5a
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: a9f69899-ee39-4900-b39a-a54d737f9614
+created_at: '2026-08-19T18:49:44.618729+00:00'
+updated_at: '2026-08-19T18:49:44.619384+00:00'
+tags:
+- 部署
+- CI
+- 交叉编译
+- OTA
+- Docker
+---
+
+# 项目 CPE 部署指南
+
+## 前置条件
+- OS: Windows + WSL2 + Docker Desktop
+- 交叉编译环境: `docker/gnu-builder.Dockerfile`
+- 代码仓库: `https://github.com/nixevol/project-cpe.git`
+- 凭证: MEMRelay MCP Token via Vaultwarden
+
+## 构建
+```bash
+cd scripts && ./build.sh
+```
+- 生成后端二进制、前端 `dist/`、可选 UPX 压缩、 OTA 元数据 `meta.json`。
+
+## 打包 OTA
+```bash
+./pack-ota.sh
+```
+- 产生 `udx710-ota-<version>.tar.gz` 与校验文件。
+
+## 部署到设备
+```bash
+./deploy.sh
+```
+- 停止服务、推送二进制与前端至 `/home/root/www/`，必要时重启设备。
+
+## CI/CD
+`.github/workflows/build-ota.yml` 包括代码拉取、交叉编译、前端打包、UPX、打包 OTA 并上传构件。
+
+**标签**: ["部署","CI","交叉编译","OTA","Docker"]