7.4 KiB
7.4 KiB
title, type, permalink, stable_id, scope, project_id, workspace_type, usage_profile_id, preference_context, document_type, revision, source_memory_ids, source_checkpoint_ids, source_file_ids, source_git_commit, source_git_commits, source_agent_sync_ids, model_connection, model_name, source_count, source_revisions, source_dispositions, cited_source_ids, job_cited_source_ids, conflicts, supersedes, preferences, source_cursor, source_hash, prompt_version, schema_version, curation_job_id, created_at, updated_at, tags, restored_from_commit
| title | type | permalink | stable_id | scope | project_id | workspace_type | usage_profile_id | preference_context | document_type | revision | source_memory_ids | source_checkpoint_ids | source_file_ids | source_git_commit | source_git_commits | source_agent_sync_ids | model_connection | model_name | source_count | source_revisions | source_dispositions | cited_source_ids | job_cited_source_ids | conflicts | supersedes | preferences | source_cursor | source_hash | prompt_version | schema_version | curation_job_id | created_at | updated_at | tags | restored_from_commit | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Ax9000WRTBuild Ongoing Maintenance & Operations Manual | curated | main/projects/6f47523e-e22e-4cdd-bd18-76e5e474ee0c/curated/development/ax9000-wrtbuild-ongoing-maintenance-operations-manual | da185d9b-8e7f-442f-b329-5bd345ab3e07 | project | 6f47523e-e22e-4cdd-bd18-76e5e474ee0c | general | null | general | maintenance | 1 | c62e79c3b986262321aa4242f0ece56c4629ae0e |
|
Sub2API | git-restore | 81 |
|
|
13 | a3dc8f049fcd5e54d4e2bc4b420c13cce749fadf5c3ca6178780171167541cf3 | 2026-08-12.3 | 3 | null | 2026-08-12T18:38:25.832891+00:00 | 2026-09-23T14:58:58.825565+00:00 |
|
6a6a895eaf |
维护与故障排查指南
本指南汇总了项目已知的缺陷、已实施的修复措施以及后续的维护任务，帮助开发者快速定位并解决常见问题。
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. 持续集成建议
- 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)
- 测试覆盖：新增单元测试覆盖
catalog.py包解析、build_config.py选项验证以及main.py的 API 参数校验。 - 安全扫描：在 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)
本指南所有信息均直接摘自已标记的源记录，无任何外部推断。