跳至主要內容

iStoreOS 功能全览

Gody2026/8/31大约 9 分钟优秀系统软路由运维

基于 iStoreOS/OpenWrt 环境 13 个运维技能（Skills）整理的功能介绍文档

1. 系统概览

iStoreOS 是基于 OpenWrt 的软路由/家庭服务器系统，核心特点：

  • 包管理：is-opkg / opkg（严禁使用 apt/yum/dnf/systemctl 等通用 Linux 命令）
  • 应用体系：iStore 应用商店（app-meta-* 元包）+ 传统 OpenWrt 包（opkg）+ Docker 容器应用（istorec）三类并存
  • 配置管理：UCI 统一配置（/etc/config/*）+ uci 命令行工具
  • 服务管理：/etc/init.d/* SysV 风格脚本 + procd
  • Web 界面：LuCI（uhttpd + rpcd）
  • 系统分区：只读 ROM（/rom 基线）+ 可写 overlay（/overlay/upper）

关键目录速查

路径用途
/etc/config/UCI 配置文件
/etc/init.d/服务启停脚本
/usr/lib/opkg/meta/*.jsoniStore 应用元数据（本地可安装集合）
/usr/libexec/istorec/<name>.shDocker 类 iStore 应用脚本
/usr/libexec/istore/overlay-backup系统全量备份工具
/overlay/upper系统可写层（备份对象）

2. 应用搜索与软件管理

2.1 应用搜索（app-search）

把「口头描述找插件」变成标准流程：

  • 数据源优先设备本地：扫描 /usr/lib/opkg/meta/*.json（与当前设备可安装集合一致）
  • 兜底数据源：随 config-dir 分发的 apps.jsonl（构建期预处理产物）
  • 输出合同：Top3 候选，每条包含 name / title / type_hint / entry / why / score
  • 确认机制：多候选时必须让用户回复 name 确认，确认后才进入安装流程

2.2 软件安装分流（package-manager）

安装前必须先分流，三类路径不同：

类型判定依据安装命令
iStore meta 应用存在 /usr/lib/opkg/meta/<name>.jsonis-opkg install app-meta-<name>
Docker 类 iStore 应用meta 的 depends 含 docker-deps，或已安装后存在 /usr/libexec/istorec/<name>.sh走 istorec 容器安装
传统 opkg 包以上都不是opkg list / info / install

支持的操作：

  • 安装：is-opkg install app-meta-<name>
  • 升级：is-opkg upgrade app-meta-<name>
  • 卸载：is-opkg remove app-meta-<name>
  • autoconf 自动配置：meta 支持时走 AUTOCONF=<name> path=<base> enable=<0|1>，可自动完成选盘、建目录、启用插件

2.3 安装后验证闭环（必须执行）

应用类型验证命令
meta/opkg 包opkg status <pkg> 或 opkg list-installed | grep <pkg>
有服务的应用/etc/init.d/<svc> status（必要时 restart）
Docker 类应用/usr/libexec/istorec/<name>.sh status 或 docker ps --all -f 'name=^/<name>$'

3. Docker 容器能力

3.1 Docker 可用性闭环（docker-basics）

标准流程：

  1. 检测安装：command -v docker; command -v dockerd
  2. 检测服务：/etc/init.d/dockerd status
  3. 安装/修复：走 iStoreOS 路径（iStore meta 优先，其次 is-opkg/opkg）
  4. 启用自启：/etc/init.d/dockerd enable && /etc/init.d/dockerd restart
  5. 验证：docker version（含 Server）+ docker info + docker ps

3.2 安装前的空间检查（关键）

任何 Docker 类应用安装/升级前必须做空间检查：

  • 检查 DockerRootDir 可用空间（< 2GiB 需处理）
  • 检查 data_root 是否在 /overlay/upper/opt/docker（系统盘上，需迁移）

3.3 Docker data_root 安全迁移（data-root-migrate）

当 Docker 数据目录在系统盘或空间不足时，迁移到数据盘：

  • 安全约束：只在用户明确确认后执行；先备份 /etc/config/dockerd 与旧目录
  • 流程：停 dockerd → 迁移数据 → 改 UCI → 重启 dockerd → 验证 → 可回滚
  • 验证：docker info 的 Docker Root Dir 与 df 空间
  • 迁移前强烈建议先做系统全量备份

4. 网络加速（iStoreEnhance / KSpeeder）

4.1 Docker 镜像加速（docker-acceleration）

解决镜像下载慢/失败的完整闭环：

  1. 前置：Docker 必须可用
  2. 一键准备：自动选盘 + autoconf（复用选盘策略）
  3. 检测安装：opkg status app-meta-istoreenhance || opkg status istoreenhance || test -x /etc/init.d/istoreenhance
  4. 未安装：is-opkg install app-meta-istoreenhance（可装到硬盘）
  5. 配置检查：uci -q show istoreenhance，确认 enabled=1 且 cache 非空
    • cache 为空时优先用 autoconf 修复，不要手改猜路径
    • 安装后 enabled 可能仍为 0（服务拒绝启动），必须设为 1 再启动
  6. 确保服务运行：/etc/init.d/istoreenhance enable && restart
  7. 验证联动：uci -q show dockerd | grep registry_mirrors
  8. 降级策略：加速不可用时直接 docker pull，但明确告知可能不走加速

4.2 KSpeeder DomainFold 下载加速（domainfold-fetch）

从 GitHub/Gist/GitLab/HuggingFace 等站点下载文件慢或失败时的加速方案。

实现原理：

  • KSpeeder 的 cmd/multi 在同一 TLS 端口上做 Host-based 路由：
    • registry.linkease.net → Docker registry mirror
    • ghcr.linkease.net → GHCR handler
    • *.linkease.net → DomainFold handler
  • DomainFold 核心：把 origin URL（如 github.com）映射到入口域名（如 gh.linkease.net）
    • 路由表：domainfold.DefaultRoutes（/gh → https://github.com）
    • remap API：POST /api/domainfold/remap，body {"url":"<origin>"} → { output, admin_path }
  • 支持范围不止 GitHub：GitLab、HuggingFace、常见包仓库、多种 AI API 域名

推荐使用 ksget 统一入口（重试 + 降级）：

尝试顺序：
1) KSpeeder DomainFold admin proxy（DNS-free）
2) 可选 PathHub 上游
3) DomainFold 入口 URL（gh.linkease.net）
4) 回退到原始 URL

5. 服务管理

解决「已安装但没生效 / 服务没起来 / 插件没启用」的通用闭环：

init.d + UCI enable flag + 验证

步骤操作
1. 确认脚本存在ls -la /etc/init.d/<service>
2. init.d 启用/etc/init.d/<service> enable && restart
3. UCI 插件启用检查uci -q show <uci_config>，常见字段 enabled=1 / enable=1 / disabled=0
4. 验证/etc/init.d/<service> status + logread | grep -iE '<service>|error|fail'

关键经验：

  • 找不到启用字段时，必须打开 /etc/init.d/<service> 查证，不要猜
  • 操作会覆盖配置/删除文件时，先提醒备份

6. 存储与选盘

当用户要「装到硬盘/U盘/指定数据目录」或遇到「磁盘满/空间不足」时，输出可用的 base path。

派生目录合同

base path 用于 is-opkg AUTOCONF=<app> path=<base> ...，is-opkg 自动派生：

<base>/
├── Configs/          (ISTORE_CONF_DIR)
├── Caches/           (ISTORE_CACHE_DIR)
├── Public/           (ISTORE_PUBLIC_DIR)
│   └── Downloads/    (ISTORE_DL_DIR)

应用级目录（如 OneAPI/）由应用自身 autoconf 拼接，不硬编码。

选盘策略

  1. 枚举挂载点与空间：mount + df -h（必要时 df -i）
  2. 选择优先级：用户指定挂载点 → 外置/数据盘（/mnt/<name>）→ 系统盘（提示风险）
  3. 可写验证：touch <base>/.istore_write_test && rm -f <base>/.istore_write_test
  4. 输出 base path + 派生目录解释

7. 系统备份与恢复

两类备份（勿混淆）

类型命令对象特点
系统全量备份（推荐）overlay-backup backup <DIR>/overlay/upper（沙箱环境含 ext_overlay/upper）恢复无需网络，恢复后自动重启
应用列表备份（可选）backupapp-meta-* 列表 + 可选依赖 ipk 重打包快速恢复应用清单

使用要点

  • 设备普通 shell 里直接用系统绝对路径：/usr/libexec/istore/overlay-backup backup <DIR>
  • <DIR> 必须在外部存储上（不能是 /、/tmp、/overlay、/ext_overlay）
  • 如果 <DIR> 是挂载点根目录，自动写入 <DIR>/istore_backup/
  • 恢复是危险操作（自动重启），执行前需明确确认

8. 故障诊断

原则：先采证据，再给结论；先分层，再深入。

最小诊断集（按需收集）

故障类型采集命令
基础信息cat /etc/os-release; uname -a; df -h; mount | head -n 80
包管理失败完整 stderr/stdout + opkg --help | head
服务异常/etc/init.d/<svc> status + logread | tail -n 200 | grep -iE '<svc>|error|fail'
Dockerdocker version + docker info + uci -q show dockerd
加速/etc/init.d/istoreenhance status + uci -q show istoreenhance
DNS/Registry按实际加速源域名探测，如 nslookup registry.linkease.net

快速分流

  • 安装失败 → 先确认是 iStore meta 还是 opkg 包
  • docker pull 失败 → 先确认 daemon 通，再检查 registry_mirrors，转加速闭环
  • 磁盘满 → 先定位挂载点（df），再清理/迁移，转选盘技能

9. LuCI Web 界面恢复

处理「安装插件后 LuCI 异常（打不开/500/空白页/登录循环）」。

核心原则

  1. 先证据：先跑只读诊断脚本
  2. 先软恢复：清缓存 + 重启 rpcd/uhttpd 往往就能恢复
  3. 不改源码优先：优先重装相关包或回退冲突插件
  4. 写操作需确认：重装前强烈建议先系统全量备份

恢复阶梯

步骤操作性质
1. 只读诊断diag.sh只读
2. 软恢复清缓存 + 重启 rpcd/uhttpd需确认
3. 定位坏文件归属包trace_owner.sh <lua路径>，对照 /rom 基线只读
4. 生成修复命令候选suggest_fix.sh <lua路径>（不执行写操作）只读
5. 重装核心包reinstall_core.sh需确认 + 先备份

10. 源码级证据采集

当不确定「服务入口/启用开关/配置字段/LuCI 实际读写逻辑」时，先采集证据再下结论。

安全约束：

  • 只读：不写 /etc/config、不改 UCI、不开停服务
  • 默认脱敏：遇到 password/token/secret/key 等字段输出前脱敏
  • 定向检索：不整树 dump /usr/lib/lua/luci

一键采集：collect.sh <name-or-keyword>（如 dockerd、istoreenhance、frpc），收集 UCI 摘要、init 脚本片段、已安装包中的 LuCI 文件清单、LuCI 目录定向匹配。

11. .run 可执行文件处理

处理 *.run 文件的统一流程：先获取 → 先检查 → 再备份 → 再确认 → 再执行 → 再留证据。

安全约束

  • .run 视为危险操作，执行前必须提示系统全量备份并确认：
    • 已备份：回复 已备份（或 CONFIRM_BACKUP_DONE=YES）
    • 明确跳过：回复 跳过备份（或 CONFIRM_BACKUP_SKIPPED=YES）
  • 先做只读检查，不要上来就 chmod +x 或直接运行

流程

步骤操作
1. 只读检查inspect.sh <FILE.run>（大小/类型/校验和/架构/空间）
2. 获取（URL 输入时）fetch.sh -o /tmp/<name>.run <URL>（支持 KSpeeder 加速下载）
3. 执行（需确认）run.sh <FILE.run|URL> [args...]（需确认环境变量）
4. 留证据执行输出保存为日志便于回溯

执行方式：

  • 设备 shell：chmod 755 <FILE.run> && <FILE.run> ...
  • 可回滚：is-opkg dotrun（记录安装，支持 is-opkg unrun 回滚，脚本自动拷贝避免删原文件）
  • 建议先试 --help/--version

12. 安全原则与操作规范

贯穿所有技能的核心原则：

原则说明
先证据再结论任何操作前先跑只读诊断，不猜测
先备份再危险操作写操作前强制提醒系统全量备份
显式确认危险操作需 CONFIRM_*=YES 环境变量或用户回复确认
脚本优先每个技能配有 scripts/ 目录，优先脚本而非手动命令
闭环验证每个操作后必须验证结果（status/version/info）
只读优先诊断、证据采集默认只读，不写系统
默认脱敏涉及密钥/password/token 的输出先脱敏

13. 典型工作流速查

场景 A：用户想装某个应用

口头描述 → app-search（Top3 候选）→ 用户确认 name
        → package-manager（分流安装）
        → service-manager（确保服务/插件启用）
        → 验证闭环

场景 B：Docker 拉镜像失败

docker-basics（确保 Docker 可用）
  → docker-acceleration（确保 kspeeder 加速生效）
  → 仍失败 → logs-and-diagnostics（采集 logread + uci show dockerd + istoreenhance）

场景 C：安装 Docker 应用前

docker-basics: check_space.sh（空间检查）
  ├─ 空间不足 → docker-data-root-migrate（迁移，需确认+备份）
  └─ 拉镜像前 → docker-acceleration: ensure_ready.sh（加速准备）

场景 D：装到指定硬盘

storage-path（选盘输出 base path）
  → package-manager：AUTOCONF=<app> path=<base> enable=1

场景 E：LuCI 打不开

luci-recovery：diag.sh（只读诊断）
  → soft_recover.sh（软恢复，需确认）
  → trace_owner.sh / suggest_fix.sh（定位问题文件）
  → reinstall_core.sh（重装，需确认+先备份）
最近更新：
贡献者: Gody
默认页脚
Copyright © 2026 Gody