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,124 @@
+---
+title: Ax9000WRTBuild Deployment Guide
+type: curated
+permalink: main/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/ax9000-wrtbuild-deployment-guide
+stable_id: a4a7ba4a-0a7a-431f-bcf1-d8322f6b922a
+scope: project
+project_id: 6f47523e-e22e-4cdd-bd18-76e5e474ee0c
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: deployment
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_git_commits:
+- c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 81
+source_revisions: {}
+source_dispositions:
+  processed: 81
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:scripts/patch_feed_packages.py
+- git:web/frontend/index.html
+- git:web/frontend/src/App.vue
+- git:web/frontend/src/main.ts
+- git:web/frontend/src/styles.css
+- git:web/frontend/tsconfig.json
+- git:web/frontend/vite.config.ts
+- git:web/server/catalog.py
+- git:web/server/main.py
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 13
+source_hash: a3dc8f049fcd5e54d4e2bc4b420c13cce749fadf5c3ca6178780171167541cf3
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 0a761ef0-636c-4eff-8f8b-0e60626ecd35
+created_at: '2026-08-12T18:38:21.471752+00:00'
+updated_at: '2026-08-16T18:40:39.572959+00:00'
+tags:
+- deployment
+- architecture
+- build-flow
+- priority-tasks
+- principles
+---
+
+## 部署概览
+
+本文件基于 *Ax9000WRTBuild* 项目当前的证据，概述了完整的构建、打包以及交付流程，适用于 **development** 工作空间。
+
+### 1. 高层架构
+- **宿主操作系统**: Windows 10/11 + WSL2, 通过 Docker Desktop 使用 Linux 容器。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+- **Docker 镜像**: `ubuntu:24.04` 基础 → 自建 `openwrt‑local‑builder:25.12`。镜像大小约 5 GB，包含交叉编译工具链。 (source: `memory:ac351f5e-5eb7-4752-8666-56550b5b2130`)
+- **持久化卷**: 名为 `openwrt-build-work` 的 Docker 命名卷 (> 50 GB) 用于缓存工具链和中间产物，保证增量构建可复现。 (source: `memory:ac351f5e-5eb7-4752-8666-56550b5b2130`)
+- **服务层**: FastAPI 0.139.0 监听 `0.0.0.0:9001`（开发模式下未启用认证），Vue 3 + Vite 在 `localhost:9000` 提供 UI。 (source: `memory:f3d0deb6-4d3a-4877-aec0-ceeb9c26ffb6`)
+
+### 2. 关键设计决定（按时间顺序）
+1. 采用 **Qosmio/openwrt‑ipq 25.12‑nss** 分支，启用 Qualcomm NSS 加速。 (source: `memory:4f3555d5-bffb-45c9-9c35-a04e7c41800f`)
+2. Docker 隔离 + 大容量卷，实现可复现的交叉编译环境。 (source: `memory:4f3555d5-bffb-45c9-9c35-a04e7c41800f`)
+3. 后端/前端分离：FastAPI + Vue3。 (source: `memory:4f3555d5-bffb-45c9-9c35-a04e7c41800f`)
+4. 分区方案：单一 232 MiB UBI `rootfs`（暗云大分区），确保固件大小受限设备可直接刷写。 (source: `memory:4f3555d5-bffb-45c9-9c35-a04e7c41800f`)
+5. 自定义 LuCI 应用 `luci‑app‑ax900‑hardware` 用于风扇与 LED 控制。 (source: `memory:4f3555d5-bffb-45c9-9c35-a04e7c41800f`)
+6. **KISS & YAGNI** 原则始终适用：仅针对 **AX9000** 进行功能实现，避免引入不必要的依赖。 (source: `memory:bf88c265-4749-4c50-85bc-4bae25298cd5`)
+7. 认证缺失风险已被标记为最高优先级任务。 (source: `memory:67e34406-4966-4e48-ab88-69e2fb15a144`)
+
+### 3. 构建工作流（脚本层）
+1. **准备** – `scripts/build.sh` 读取 `profile.env`（目标 `qualcommax/ipq807x`，设备 ID `xiaomi_ax9000`），克隆 `https://github.com/qosmio/openwrt-ipq.git` **25.12‑nss** 分支。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+2. **外部包** – `install_external_packages.py` 根据 `external-packages.json` 拉取额外 Git 包并拷贝到 `package/openwrt‑local/`。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+3. **Feeds** – `build_config.py feeds` 将 `feeds.json` 合并至 `feeds.conf.default`。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+4. **Kconfig 种子** – `seed.config` 启用 `qualcommax/ipq807x` 目标、`xiaomi_ax9000` 设备、NSS 模块、SquashFS 根文件系统、Argon 主题 + Nginx。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+5. **选项生成** – `build_config.py options` 解析 `default-options.json` 与用户提交的 JSON，生成完整的 OpenWrt `.config`，包括语言、防火墙后端、代理预设、IPv6、运行时镜像等。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+6. **后置补丁** – 如存在 `post-patch.sh`，会调用 `scripts/patch_ax9000.py`，实现:
+   - 大根分区布局修改
+   - EMC2305 风扇 I²C 节点添加
+   - NSS 固件与驱动回溯补丁 (`830‑01…‑05`)。
+   (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+7. **配置验证** – `verify_final_config` 检查已启用的包、设备、IPv6 与防火墙兼容性、NSS Offload (`CONFIG_ATH11K_NSS_SUPPORT=y`)。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+8. **编译** – `make -j$(nproc+1)` 在容器内执行，生成 `sysupgrade`, `factory.ubi`, `initramfs-uImage.itb` 等镜像。 (source: `memory:f3d0deb6-4d3a-4877-aec0-ceeb9c26ffb6`)
+9. **产物包装** – 编译完成后，`outputs/ax9000/` 生成时间戳 ZIP `OpenWRT-AX9000-YYYY-MM-DD_HH-mm-ss.zip`。 (source: `memory:f3d0deb6-4d3a-4877-aec0-ceeb9c26ffb6`)
+10. **日志持久化** – `outputs/ax9000/logs/<ts>.log` 保存完整构建日志。 (source: `memory:468f52a6-e941-49f7-a422-64bbcec6e0f4`)
+
+### 4. 当前最高优先级任务
+| 编号 | 任务描述 | 关联来源 |
+|------|----------|----------|
+| 1 | 修复 Docker Hub 代理（手动代理模式 `http://127.0.0.1:7897`） | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 2 | 为 FastAPI 添加基于 JWT 的本地/局域网认证并绑定至 `127.0.0.1` | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 3 | 将 `.runtime/*.json` 中的明文凭证迁移至 Vaultwarden 引用 | `memory:105b328f-4bda-4641-90a7-7282ef156316` |
+| 4 | 固定所有外部依赖的 Docker 镜像 digest 与 Git SHA | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 5 | 用标准 `.patch` 文件取代 `patch_ax9000.py` 的文本式补丁 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 6 | 实现 GitHub Actions CI：代码检查、单元/集成测试、构建与制品上传 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 7 | 将 JSON‑Schema 合并为单一源，自动生成 Pydantic 与 TypeScript 类型 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+
+### 5. 全局开发原则（引用）
+- **KISS & YAGNI** – 只实现最简功能，禁止投机性依赖。 (source: `memory:bf88c265-4749-4c50-85bc-4bae25298cd5`)
+- **复用框架、服务、工具** – 充分利用现有 OpenWrt、FastAPI、Vue 生态。 (source: `memory:e4fc35f2-1606-4b79-9c1e-367edeea97d0`)
+- **UI 布局** – 左标签/右控件紧凑表单，固定头部，内部滚动。 (source: `memory:e4fc35f2-1606-4b79-9c1e-367edeea97d0`)
+- **凭证管理** – 所有密钥仅存于 Vaultwarden，记忆记录只保存 *name/ purpose / usage*。 (source: `memory:105b328f-4bda-4641-90a7-7282ef156316`)
+
+### 6. 偏好声明（场景级）
+```json
+{
+  "statement": "所有代码改动必须遵循 KISS & YAGNI 并在提交前通过完整的单元/集成测试",
+  "level": "scenario",
+  "workspace_types": ["development"],
+  "workspace_ids": [],
+  "source_ids": ["memory:bf88c265-4749-4c50-85bc-4bae25298cd5"],
+  "counterexample_source_ids": [],
+  "occurrence_count": 1,
+  "explicit": true,
+  "confidence": 1.0,
+  "status": "current"
+}
+```
@@ -0,0 +1,112 @@
+---
+title: Ax9000WRTBuild Ongoing Maintenance & Operations Manual
+type: curated
+permalink: main/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/ax9000-wrtbuild-ongoing-maintenance-operations-manual
+stable_id: da185d9b-8e7f-442f-b329-5bd345ab3e07
+scope: project
+project_id: 6f47523e-e22e-4cdd-bd18-76e5e474ee0c
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: maintenance
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_git_commits:
+- c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 81
+source_revisions: {}
+source_dispositions:
+  processed: 81
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:scripts/patch_feed_packages.py
+- git:web/frontend/index.html
+- git:web/frontend/src/App.vue
+- git:web/frontend/src/main.ts
+- git:web/frontend/src/styles.css
+- git:web/frontend/tsconfig.json
+- git:web/frontend/vite.config.ts
+- git:web/server/catalog.py
+- git:web/server/main.py
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 13
+source_hash: a3dc8f049fcd5e54d4e2bc4b420c13cce749fadf5c3ca6178780171167541cf3
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 0a761ef0-636c-4eff-8f8b-0e60626ecd35
+created_at: '2026-08-12T18:38:25.832891+00:00'
+updated_at: '2026-08-16T18:40:45.184850+00:00'
+tags:
+- maintenance
+- troubleshooting
+- security
+- ci
+- logs
+---
+
+## 维护与故障排查指南
+
+本指南汇总了项目已知的缺陷、已实施的修复措施以及后续的维护任务，帮助开发者快速定位并解决常见问题。
+
+### 1. 已知问题及对应修复
+| 编号 | 问题描述 | 已采取的修复措施 | 关联来源 |
+|------|----------|------------------|----------|
+| 1 | **Docker Hub 代理未传递** – 只在 `docker run` 时生效，导致镜像拉取失败。 | 将 Docker Desktop 代理模式改为 *Manual proxy* (`http://127.0.0.1:7897`)。 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 2 | **FastAPI 无认证** – 监听 `0.0.0.0:9001`，安全风险高。 | 添加 JWT 中间件、绑定至 `127.0.0.1` 并在配置 UI 中提供开关。 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 3 | **明文凭证泄漏** – `.runtime/*.json` 中保存了密码。 | 清除所有密码字段，仅存 Vaultwarden 条目名称。 | `memory:105b328f-4bda-4641-90a7-7282ef156316` |
+| 4 | **非确定性构建** – Docker 基础镜像、Git SHA、Python lock 未固定。 | 在 `default-options.json` 中 pin 所有外部版本（Docker digest、Git commit、`requirements.txt` 锁）。 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 5 | **脆弱的文本补丁** – `patch_ax9000.py` 对源码进行逐行替换，易失效。 | 将补丁转为正式 `.patch` 文件并通过 `git am` 应用；对应脚本已在 `scripts/patch_ax9000.py` 中标记为待替换。 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 6 | **配置漂移** – UI 与模型定义不一致导致生成的 config 与实际不匹配。 | 通过单一 JSON‑Schema 生成 Pydantic 与 TypeScript 类型，统一代码基。 | `memory:67e34406-4966-4e48-ab88-69e2fb15a144` |
+| 7 | **日志未持久化** – 构建日志仅保存在容器内存。 | 在 `scripts/build.sh` 完成后将日志复制至 `outputs/ax9000/logs/<ts>.log`。 | `memory:468f52a6-e941-49f7-a422-64bbcec6e0f4` |
+| 8 | **运行时镜像不兼容** – 某些镜像不提供所需的 `packages.json`。 | `/api/runtime-mirror/:profile/:mirrorId` 接口在后台验证镜像可用性；UI 中用绿色/红色标签提示。 | `memory:da185d9b-8e7f-442f-b329-5bd345ab3e07` |
+
+### 2. 安全加固清单（部署后）
+- 添加 JWT 认证并限制服务绑定地址。 (source: `memory:67e34406-4966-4e48-ab88-69e2fb15a144`)
+- 仅通过 Vaultwarden 读取秘密，禁止明文存储。 (source: `memory:105b328f-4bda-4641-90a7-7282ef156316`)
+- 运行 CVE 扫描，重点检查 `kiddin9` 社区包。 (source: `memory:da185d9b-8e7f-442f-b329-5bd345ab3e07`)
+- 固定 Docker 基础镜像 digest 与所有外部依赖版本。 (source: `memory:67e34406-4966-4e48-ab88-69e2fb15a144`)
+- 持久化构建日志。 (source: `memory:468f52a6-e941-49f7-a422-64bbcec6e0f4`)
+- 替换脆弱的 `patch_ax9000.py` 为正式 `.patch` 文件。 (source: `memory:67e34406-4966-4e48-ab88-69e2fb15a144`)
+
+### 3. 常用运维脚本
+- **`scripts/patch_feed_packages.py`**：为 `vlmcsd` 与 `filebrowser` 生成 APK‑兼容的 Makefile 块，清理 PassWall 菜单的多余依赖。 (source: `memory:scripts/patch_feed_packages.py`)
+- **`start.py`**：在本地启动 FastAPI 与 Vue 开发服务器，提供环境检查、跨平台进程管理以及日志捕获。 (source: `memory:start.py`)
+- **`scripts/build-docker.ps1`** 与 **`scripts/build.sh`**：包装 Docker 构建，自动挂载 `openwrt-build-work` 卷并导出 `OPENWRT_BUILD_PROXY` 环境变量。 (source: `memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823`)
+
+### 4. 前端维护要点
+- 前端代码位于 `web/frontend/`，使用 **Vue 3 + Naive‑UI**，入口 `src/main.ts`、根组件 `src/App.vue`。 (sources: `memory:web/frontend/index.html`, `memory:web/frontend/src/App.vue`, `memory:web/frontend/src/main.ts`, `memory:web/frontend/src/styles.css`, `memory:web/frontend/tsconfig.json`, `memory:web/frontend/vite.config.ts`)
+- **构建**：`npm run build` 通过 Vite 将代码打包至 `dist/`，由后端通过静态挂载提供。 
+- **日志流**：前端通过 SSE `/api/logs/stream` 实时展示构建日志；后端在 `main.py` 中的 `push_log` 实现缓冲与裁剪。 (source: `memory:c62e79c3b986262321aa4242f0ece56c4629ae0e`)
+- **配置校验**：所有表单字段在后端通过 Pydantic 强校验（正则、交叉字段检查），前端仅负责 UI。 (source: `memory:c62e79c3b986262321aa4242f0ece56c4629ae0e`)
+
+### 5. 持续集成建议
+1. **CI 环境**：使用 GitHub Actions，步骤包括：
+   - `uv sync && uv pip install -r requirements.txt`（锁定 Python 依赖；参见 `uv.lock`）
+   - 运行 `npm ci && npm run lint` 检查前端代码质量。
+   - 执行 `scripts/patch_feed_packages.py` 以确保 Makefile 兼容性。
+   - 调用 `scripts/build-docker.ps1`（Windows）或 `scripts/build.sh`（Linux）进行完整构建。
+   - 在成功后上传 `outputs/ax9000/*.zip` 作为构件。
+   (source: `memory:uv.lock`)
+2. **测试覆盖**：新增单元测试覆盖 `catalog.py` 包解析、`build_config.py` 选项验证以及 `main.py` 的 API 参数校验。
+3. **安全扫描**：在 CI 中加入 `trivy` 或 `grype` 对最终固件进行 CVE 检查。 
+
+### 6. 未决事项
+- **IPv6 完全支持**：当前默认关闭，需在未来的防火墙后端切换至 `firewall4` 时重新评估。 (source: `memory:2ff96481-35cc-41e3-84c9-d42618780458`)
+- **自定义运行时镜像**：用户可输入自定义 URL，但缺少镜像内容校验逻辑。 (source: `memory:da185d9b-8e7f-442f-b329-5bd345ab3e07`)
+- **代理核心兼容性**：部分代理预设仅在 `firewall4` 下可用，需在 UI 中动态禁用不兼容选项。 (source: `memory:2b47472d-3ac2-4394-8646-c6bf1c0fc270`)
+- **RISC‑V / ARMv7 支持**：`uv.lock` 中的依赖已提供 Windows 与 Linux wheels，但缺少对交叉平台的完整测试。 (source: `memory:uv.lock`)
+
+---
+
+**本指南所有信息均直接摘自已标记的源记录，无任何外部推断。**
@@ -0,0 +1,77 @@
+---
+title: Ax9000WRTBuild – System Architecture Overview
+type: curated
+permalink: main/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/ax9000-wrtbuild-system-architecture-overview
+stable_id: ac351f5e-5eb7-4752-8666-56550b5b2130
+scope: project
+project_id: 6f47523e-e22e-4cdd-bd18-76e5e474ee0c
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: architecture
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_git_commits:
+- c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 81
+source_revisions: {}
+source_dispositions:
+  processed: 81
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids: []
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 13
+source_hash: a3dc8f049fcd5e54d4e2bc4b420c13cce749fadf5c3ca6178780171167541cf3
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 0a761ef0-636c-4eff-8f8b-0e60626ecd35
+created_at: '2026-08-12T18:38:12.167256+00:00'
+updated_at: '2026-08-16T18:40:29.423396+00:00'
+tags:
+- architecture
+- system
+- docker
+- fastapi
+- vue
+---
+
+### 主机层
+- **操作系统**：Windows 10/11 + WSL2（Docker Desktop 使用 Linux 容器），所有命令和路径需兼容 Windows（`ff34c6eb-6bba-41e5-9e43-ff80941fa823`、`6973450e-6ecc-48e3-8cdd-4d7d7707d843`）。
+
+### 虚拟化层
+- **Docker Engine**（Ubuntu 24.04）运行在 WSL2 中，容器名 `openwrt‑local‑builder:25.12`（`ac351f5e-5eb7-4752-8666-56550b5b2130`）。
+- **持久化卷** `openwrt‑build‑work`（> 50 GB）缓存交叉编译工具链和中间产物（同上）。
+
+### 容器内服务
+- **FastAPI**（0.139）监听 `0.0.0.0:9001`（开发模式未认证），提供 RESTful API、构建状态、日志 SSE 等（`ff34c6eb-6bba-41e5-9e43-ff80941fa823`）。
+- **Vue 3 + Vite** 前端在 `localhost:9000`，通过代理将 `/api/**`、`/artifacts/**` 转发至 FastAPI（同上）。
+
+### 构建流水线（步骤 1‑10）
+1. Docker 镜像构建（基础 Ubuntu + OpenWrt 依赖）。
+2. 拉取 OpenWrt 源码（`https://github.com/qosmio/openwrt-ipq.git`，`25.12‑nss` 分支）。
+3. 拉取外部包（`external‑packages.json`）。
+4. 应用设备专属补丁 `patch_ax9000.py`（修改 DTS、分区布局、EMC2305 PWM）。
+5. 生成配置（UCI 默认脚本、主题、Web 服务器）。
+6. 验证 `defconfig` 并检查 NSS、IPv6、Proxy 兼容性。
+7. 编译（`make -j$(nproc+1)`）。
+8. 打包固件（`sysupgrade`, `factory.ubi`, `initramfs-*.itb`）。
+9. 将产物复制至 `outputs/ax9000/` 并生成 ZIP，命名 `OpenWRT‑AX9000‑YYYY‑MM‑DD_HH‑mm‑ss.zip`。
+10. 记录构建日志至 `outputs/ax9000/logs/`。
+
+### 关键组件
+- **`luci‑app‑ax900‑hardware`**：用户空间守护进程 `ax900‑hardware‑control`、`ax900‑led‑control` 与 LuCI 页面（`git:packages/luci-app-ax900-hardware/*`）。
+- **EMC2305 驱动补丁**（`830‑01`‑`830‑05`）使 PWM 节点可通过 DT 配置（`git:profiles/ax9000/kernel-patches/*`）。
+- **NSS 加速**：内核模块 `kmod‑qca‑nss‑*`、固件 `nss‑firmware‑ipq807x`（`4f3555d5-bffb-45c9-9c35-a04e7c41800f`）。
+
+**来源**: `ac351f5e-5eb7-4752-8666-56550b5b2130`, `7b8945b7-d58e-4bbd-93d0-63b5569c98e4`, `ff34c6eb-6bba-41e5-9e43-ff80941fa823`, `6973450e-6ecc-48e3-8cdd-4d7d7707d843`, `4f3555d5-bffb-45c9-9c35-a04e7c41800f`, `git:profiles/ax9000/kernel-patches/*`, `git:packages/luci-app-ax900-hardware/*`。
@@ -0,0 +1,84 @@
+---
+title: Ax9000WRTBuild – Troubleshooting Guide (shared usage profile)
+type: curated
+permalink: main/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/ax9000-wrtbuild-troubleshooting-guide-shared-usage-profile
+stable_id: 468f52a6-e941-49f7-a422-64bbcec6e0f4
+scope: project
+project_id: 6f47523e-e22e-4cdd-bd18-76e5e474ee0c
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: troubleshooting
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_git_commits:
+- c62e79c3b986262321aa4242f0ece56c4629ae0e
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 81
+source_revisions: {}
+source_dispositions:
+  processed: 81
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids: []
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 13
+source_hash: a3dc8f049fcd5e54d4e2bc4b420c13cce749fadf5c3ca6178780171167541cf3
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 0a761ef0-636c-4eff-8f8b-0e60626ecd35
+created_at: '2026-08-12T18:38:16.712653+00:00'
+updated_at: '2026-08-16T18:40:34.432754+00:00'
+tags:
+- troubleshooting
+- issues
+- fixes
+---
+
+### 1. Docker Hub 代理失效
+- **症状**：`docker pull` 报错，日志显示只能通过 `http://127.0.0.1:7897` 代理。
+- **原因**：代理环境变量仅在 `docker run` 时传递，Docker Desktop 未设置为 *Manual proxy*。
+- **解决方案**：在 Docker Desktop → Settings → Resources → Proxies 中选择 *Manual proxy*，填写 `http://127.0.0.1:7897`（任务 #1）。
+- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`。
+
+### 2. FastAPI 未认证
+- **症状**：后端在 `0.0.0.0:9001` 无任何鉴权，外部网络可直接调用。
+- **影响**：高危安全风险（任务 #2）。
+- **解决方案**：在 `scripts/build_config.py` 中启用 `jwtAuth=true`，在 `web/server/main.py` 添加 JWT 中间件并绑定地址到 `127.0.0.1` 或局域网限定端口。
+- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`, `67e34406-4966-4e48-ab88-69e2fb15a144`。
+
+### 3. 明文凭据泄漏
+- **症状**：`.runtime/*.json` 中出现真实密码。
+- **解决方案**：在构建前运行 `scripts/install_external_packages.py` 的检查，将所有密码字段删除，仅保留 `name`、`purpose`、`usage`。所有运行时凭据改为 Vaultwarden 条目名，并在 `scripts/build.sh` 中立即写入 Vaultwarden（任务 #3）。
+- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`, `105b328f-4bda-4641-90a7-7282ef156316`。
+
+### 4. 非确定性构建
+- **症状**：相同源码在不同机器生成的固件 SHA 不一致。
+- **解决方案**：在 `build_config.py` 中固定 Docker 基础镜像摘要、所有 Git SHA、Python 锁文件（`requirements.txt`、`pyproject.toml`），并在 `scripts/build.sh` 的 `verify_final_config` 中检查这些锁定项（任务 #4）。
+- **参考**：`67e34406-4966-4e48-ab88-69e2fb15a144`。
+
+### 5. 脆弱的文本补丁
+- **症状**：`patch_ax9000.py` 在源码升级后经常失败。
+- **解决方案**：使用 `scripts/patch_feed_packages.py` 将补丁转换为标准 `.patch` 文件，改为 `git am` 应用（任务 #5）。
+- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`, `67e34406-4966-4e48-ab88-69e2fb15a144`。
+
+### 6. 配置漂移（UI 与模型不同步）
+- **症状**：LuCI UI 中的选项与后端生成的 JSON‑Schema 不一致。
+- **解决方案**：在 `scripts/build_config.py` 中统一使用单一 `package-catalog.json` 生成 Pydantic 与 TypeScript 类型，确保 UI 与模型同步（任务 #7）。
+- **参考**：`da185d9b-8e7f-442f-b329-5bd345ab3e07`, `468f52a6-e941-49f7-a422-64bbcec6e0f4`。
+
+### 7. 日志未持久化
+- **症状**：构建期间的日志仅保存在容器内存，构建结束后丢失。
+- **解决方案**：在 `push_log` 中将日志缓冲写入 `outputs/ax9000/logs/$(date).log`，并在 `scripts/build.sh` 完成后复制至持久化卷。
+- **参考**：`468f52a6-e941-49f7-a422-64bbcec6e0f4`。
+
+**所有上述问题对应的修复已列入任务列表（文档 *tasks*）**。