---
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: general
usage_profile_id: null
preference_context: general
document_type: deployment
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:21.471752+00:00'
updated_at: '2026-09-23T14:58:56.167185+00:00'
tags:
- deployment
- architecture
- build-flow
- priority-tasks
- principles
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

## 部署概览

本文件基于 *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"
}
```