分析日期：2026-05-22 目标设备：极空间 T2（SSH root 接入分析） ZOS 版本：V1.2.0200068

本篇是系列的第一篇，给出整机的全景视图：基础系统、存储拓扑、应用部署模型、启动流程和 API 网关。

一、基础操作系统

ZOS —— 基于 Debian 11 (Bullseye) 的定制 NAS 系统

内核启动参数：storagemedia=emmc androidboot.storagemedia=emmc androidboot.mode=normal，说明引导流程借鉴了 Android 的 boot 架构（详见第 2 篇《底层系统》）。

二、存储拓扑

物理存储布局

eMMC 29.1GB（系统盘）
├── p1      4MB     启动固件
├── p2      4MB     启动固件
├── p3      64MB    (保留)
├── p4      32MB    (保留)
├── p5      32MB    (保留)
├── p6      14GB    ext4  →  /                     根文件系统
├── p7      128MB   (保留)
├── p8      12GB    ext4  →  /zspace               系统应用与配置
├── p9      1GB     ext4  →  /zspace/applications/logs  应用日志
├── p10     64MB    (保留)
└── p11     1.8GB   (保留/恢复)

NVMe SSD ×2（476.9GB ×2，数据盘，RAID1）
├── p1      3GB     ×2  →  md0   RAID1  →  swap
├── p2      8MB     ×2  (引导)
├── p3      20GB    ×2  →  md1   RAID1  →  /zspace/zsrp   运行时数据
└── p4      453GB   ×2  →  md100 RAID1  →  /data_n001     用户数据

文件系统类型

设计要点

• 系统与数据分离：eMMC 承载系统文件（不可变），NVMe RAID1 承载用户数据（可变）
• /data_n001 使用 btrfs，启用 nodatacow + ssd + discard，支持子卷快照（.snapshot）
• zfuse.zfsv3 是自研文件系统，不是 ZFS，提供分层/联合挂载能力

注：关于 zfuse 的实现细节，第 2 篇《底层系统》有修正——它不是纯 FUSE 用户态方案，而是带 135KB 内核模块的混合实现，用于存储配额管理。

三、应用部署架构（三层模型）

┌──────────────────────────────────────────────────────────────┐
│  Layer 3：用户应用 (App-*.service)                            │
│  /data_n001/appstore/pkg/ → /var/appstore/pkg/               │
│                                                              │
│  video │ photoAlbum │ music │ bookLib │ comics               │
│  downloads │ autoBackup │ backupCenter                       │
│  camera │ family │ zclasses │ zjdxb                          │
│  thunder │ onlyoffice │ ddns │ filerescue                    │
│  hsk │ imgProcessing │ zvirusscan                            │
│                                                              │
│  Go 二进制（20~40MB），systemd 管理，独立进程                  │
├──────────────────────────────────────────────────────────────┤
│  Layer 2：核心服务 (z* 原生 systemd service)                  │
│  /zspace/applications/services/                              │
│                                                              │
│  zbakv2 │ zdrive │ zds │ zfrpc │ zhelper │ znetdiskv2       │
│                                                              │
│  与 Layer 1 混合部署，共用同一套 infrastructure               │
├──────────────────────────────────────────────────────────────┤
│  Layer 1：基础设施 + 平台服务（nas_service 脚本启动）          │
│  /zspace/applications/services/                              │
│                                                              │
│  ┌─────────────────┬────────────────┬─────────────────────┐ │
│  │ 数据层           │ 存储层          │ 网络层               │ │
│  │ redis            │ storagepool    │ openresty (API网关)  │ │
│  │ MySQL/MariaDB    │ zspoolv3       │ samba / nfs / ftp    │ │
│  │ PostgreSQL       │ zfuse          │ webdav / afp         │ │
│  │ minio (S3)       │ zdrive         │ syncthing            │ │
│  │                  │ mergerfs       │ aria2 / transmission │ │
│  ├─────────────────┼────────────────┼─────────────────────┤ │
│  │ 平台服务          │ 容器            │ 媒体                 │ │
│  │ go-baseset (API) │ zdocker (自研)  │ player-qt            │ │
│  │ go-basesetAdv    │                │ transcode            │ │
│  │ zbasic (用户)    │                │ media-converter      │ │
│  │ zsysutil         │                │                      │ │
│  └─────────────────┴────────────────┴─────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

应用包标准结构

以 photoAlbum 为例：

/var/appstore/pkg/photoAlbum/
├── zalbumv2            Go 静态链接二进制（41MB），主程序
├── start.sh            启动脚本
├── stop.sh             停止脚本
├── restart.sh          重启脚本
├── realstart.sh        实际启动逻辑（被 start.sh 调用）
├── DB/                 数据库迁移文件
├── script/             辅助脚本
├── ui/                 前端静态资源
├── systemd/            systemd unit 文件
│   └── App-photoAlbum.service
└── version             版本号

关键发现：所有应用都是原生二进制，不走 Docker

与群晖/威联通不同，极空间的应用不跑在 Docker 容器里。每个 App 是独立的 Go 二进制，通过 systemd 管理，直接运行在宿主机上，共享 redis、mysql、nginx 等基础设施。这种设计在 ARM 嵌入式场景下更轻量。

四、启动流程

systemd
  │
  ├── 基础系统服务
  │     ssh, cron, NetworkManager, avahi, bluetooth, dhcpcd
  │     syslog-ng, dbus, polkit, earlyoom
  │
  ├── xnasdesktop-service.service
  │     │
  │     └── /zspace/shell/nas_service（主启动脚本）
  │           │
  │           ├── 1. 时间同步 → 工厂数据加载
  │           ├── 2. zdrive → redis → leds → openresty
  │           ├── 3. storagepool → zspoolv3 → zfuse（就绪）
  │           ├── 4. upgrader → downloader → zflash
  │           ├── 5. samba → webapi（实际启动 zbasic）
  │           └── 6. cron 任务重置
  │
  └── App-*.service（systemd，After=network.target）
        │
        ├── App-video.service         → /var/appstore/pkg/video/zvideov2
        ├── App-photoAlbum.service    → /var/appstore/pkg/photoAlbum/zalbumv2
        ├── App-music.service         → ...
        ├── App-downloads.service     → downloader
        ├── App-thunder.service       → 迅雷
        ├── App-onlyoffice.service    → OnlyOffice
        └── ...（所有用户应用并行启动）

每个服务通过自研的 singleton.sh 防重复启动，启动日志写入 /zspace/applications/logs/<服务名>/start.log。

五、通信架构：OpenResty 统一 API 网关

                          ┌──────────────────┐
    浏览器 / 手机客户端 ──►│  :80   主站 Web   │
                          │  :5056 外网接入    │
                          └────────┬─────────┘
                                   │
                     nginx / OpenResty + LuaJIT
                                   │
           ┌───────┬───────┬───────┼───────┬───────┬───────┐
           ▼       ▼       ▼       ▼       ▼       ▼       ▼
        :2999   :5055   :8020   :8021   :8026   :8080   :8088
        内部API  动态    WebAPI   视频    网盘    PC端   HDMI
        网关    代理            服务    服务    Web    输出
           │       │
           ▼       ▼
      :8050      各 App 后端端口
    go-baseset   (zalbumv2, zvideov2, ...)
    (核心 API)

端口映射

OpenResty 中间件

• rewrite_token.lua：token 认证与改写
• nas_share_cache：分享链接缓存（2MB lua_shared_dict）
• mdrwuris.lua：URI 读写权限控制
• 日志通过 syslog 发送到本地 127.0.0.1:514

六、关键技术发现

1. zdocker 不是裸 Docker

/zspace/applications/services/zdocker/zdocker 是 Go 编译的二进制（动态链接），不是 Docker Engine。它是极空间自研的容器管理器，提供 Docker 兼容的镜像/容器生命周期管理。完整的逆向分析见第 5 篇《Docker 容器体系》。

• 标准 containerd 存在于 /opt/containerd/，另有完整 dockerd/containerd 栈随 portainer 目录分发
• portainer 配置文件存在于 /data/，说明 zdocker 暴露了 Docker API 兼容层
• 设计意图：为普通用户提供 Docker 使用体验，同时把复杂度封装在产品层

2. zfuse 不是 ZFS

挂载类型 zfuse.zfsv3，是自研文件系统，提供类似 UnionFS/OverlayFS 的分层挂载能力。真正的 ZFS 内核模块并未加载（lsmod | grep zfs 无结果）。

作用：在 /tmp/zfsv3 上提供一个合并视图，将多个物理存储池的目录统一呈现。

3. Android 引导痕迹

内核 cmdline 包含 androidboot.storagemedia=emmc androidboot.mode=normal，分区结构也类似 Android（独立的 boot/recovery/system/vendor），说明引导流程借鉴（或直接复用了）Rockchip RK3568 的 Android BSP。

4. OTA 更新框架

/zspace/update/ 下有完整的升级系统：

• pkg/：更新包
• upgrader/：升级程序
• bak/：回滚备份
• state：当前升级状态

详见第 3 篇《OTA 升级体系》。

5. 数据库架构

三层数据库设计：

• MySQL/MariaDB：系统核心数据（用户、权限、配置）
• PostgreSQL：部分应用数据（photoAlbum 等，见 pg_start.sh）
• SQLite：轻量应用数据（大量 sqlite 文件在 /zspace/zsrp/sqlite/ 下）

七、技术栈总览