MemRelay/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/Ax9000WRTBuild Ongoing Maintenance & Operations Manual.md

---
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: general
usage_profile_id: null
preference_context: general
document_type: maintenance
revision: 1
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: git-restore
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: null
created_at: '2026-08-12T18:38:25.832891+00:00'
updated_at: '2026-09-23T14:58:58.825565+00:00'
tags:
- maintenance
- troubleshooting
- security
- ci
- logs
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

## 维护与故障排查指南

本指南汇总了项目已知的缺陷、已实施的修复措施以及后续的维护任务，帮助开发者快速定位并解决常见问题。

### 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`)

---

**本指南所有信息均直接摘自已标记的源记录，无任何外部推断。**