调研目标：极空间自研容器管理平台 zdocker 的架构、功能边界与实现原理 调研方式：远程服务器逆向分析（T2 设备，ZOS V1.2.0200068） 调研日期：2026-05-22

一、核心结论

zdocker 不是 Docker Engine 的替代，而是基于 Docker Engine 之上的业务封装层。

极空间在标准 Docker 栈（dockerd + containerd + runc）之上，自研了一套 Go 编写的容器管理中间件，核心解决三个问题：

1. 应用商店化 —— 把第三方 Docker 应用包装成一键安装/卸载/升级的商品
2. Android 容器（AIC） —— 在 NAS 上运行带 GPU/HDMI/USB 的 Android 容器
3. Compose 与定时任务 —— 管理 docker-compose 项目和容器启停策略

zdocker 本身不直接暴露 HTTP 端口，而是通过 Unix socket / 内部 IPC 与 go-baseset 通信，由 baseset 作为 API 网关对外服务。

二、整体架构（四层模型）

┌─────────────────────────────────────────────────────────────┐
│ Layer 4：前端（PC Web / 手机 App / HDMI 界面）                │
│         通过 OpenResty → go-baseset (:8050) 访问             │
├─────────────────────────────────────────────────────────────┤
│ Layer 3：API 网关 + 业务编排                                  │
│         go-baseset (:8040) ←→ baseset (:8038)               │
│         用户认证、路由转发、请求聚合                             │
├─────────────────────────────────────────────────────────────┤
│ Layer 2：容器业务管理层                                        │
│         zdocker (Go)  ←→  dockerm (C++, :8048)              │
│         │                      │                             │
│         ├─ 应用商店 (AppStoreTaskV2)                         │
│         ├─ Android 容器 (CloudPhone / AIC)                   │
│         ├─ Compose 项目管理                                  │
│         ├─ 镜像下载/更新/加速器                               │
│         └─ 容器定时启停 (Cron)                               │
│                      │                                       │
│                      └─ 调用 shell 脚本执行实际 Docker 操作    │
├─────────────────────────────────────────────────────────────┤
│ Layer 1：容器运行时 + Web UI                                  │
│         Docker Engine (dockerd + containerd + runc)         │
│         portainer / zportainer (Docker Web UI)              │
│         overlay2 存储驱动                                     │
└─────────────────────────────────────────────────────────────┘

关键进程与端口

三、zdocker 本体分析

3.1 二进制特征

file /zspace/applications/services/zdocker/zdocker
# ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked
# Go BuildID=8_Aaqf7v4pLntzMQrper/1l6COKENhwUJ72CblZ_S/...
# with debug_info, not stripped

• 大小：27.9 MB（27931256 字节）
• Go 版本：1.23.3（通过构建脚本和符号表交叉验证）
• 架构：ARM64（aarch64），与 T2 的 RK3568 匹配
• 符号表：未 strip，保留了完整的调试信息和源码路径

3.2 源码路径暴露

二进制中的调试符号暴露了 Jenkins CI 构建路径：

/var/jenkins_home/home/workspace/services/zdocker/release/online_t020/
├── model/appstorepredefine.go
├── model/container_list.go
├── model/appstore.go
├── model/apps.go
├── model/compose_cron.go
├── model/tiandingxingandroid.go
├── model/tiandingxingandroid_android_check.go
└── ...

这说明：

• zdocker 源码在极空间的 Jenkins CI 上以 单仓（monorepo） 方式管理
• 构建产物按设备型号分支（online_t020 = T2 线上版）
• 使用了 GORM 作为 ORM，gin 作为 Web 框架

3.3 依赖的开源库

通过 Go module 缓存路径识别出主要依赖：

3.4 命令行接口

/zspace/applications/services/zdocker/zdocker --help
# 输出只有两项：
#   -v    application version
#   -version  application version

zdocker 不是命令行工具，而是无头守护进程。 启动后没有监听 TCP 端口，而是通过 Unix socket 或文件系统事件与上层服务通信。其标准输出重定向到 /zspace/applications/logs/zdocker/zdocker.log。

四、数据存储模型

zdocker 使用 SQLite 作为元数据存储，所有数据库文件位于 /zspace/applications/services/zdocker/config/ 和 /zspace/zsrp/zdocker/。

4.1 数据库文件

4.2 核心表结构

apps（已安装应用）

CREATE TABLE `apps` (
  `id` text,
  `app_name` text,
  `container_id` text,
  `created_at` datetime,
  `updated_at` datetime,
  `status` text,
  PRIMARY KEY (`id`)
);
CREATE UNIQUE INDEX `idx_apps_container_id` ON `apps`(`container_id`);

containers（容器定时配置）

CREATE TABLE `containers` (
  `container_id` text,
  `icon` text,
  `cron` numeric,
  `cron_start` text,
  `cron_start_enable` numeric DEFAULT false,
  `cron_start_once` text,
  `cron_start_once_enable` numeric DEFAULT false,
  `cron_stop` text,
  `cron_stop_enable` numeric DEFAULT false,
  `cron_stop_once` text,
  `cron_stop_once_enable` numeric DEFAULT false,
  PRIMARY KEY (`container_id`)
);

compose_projects（Compose 项目）

CREATE TABLE `compose_projects` (
  `id` text,
  `project_name` text,
  `file_path` text,
  `storage_path` text,
  `created_at` datetime,
  `updated_at` datetime,
  `status` text,
  `path_valid` numeric,
  `app` text,
  PRIMARY KEY (`id`)
);
CREATE UNIQUE INDEX `idx_compose_projects_project_name` ON `compose_projects`(`project_name`);

五、应用商店系统（AppStoreTaskV2）

5.1 设计目标

把 Docker 容器包装成"应用"，让普通用户像安装手机 App 一样安装 Docker 应用，无需接触命令行。

5.2 应用预定义数据（Predefine）

每个应用有一个 predefine JSON 字段，包含：

• 多语言元数据：名称、简介、帮助链接（zh_cn / en_us / ja_jp）
• 图标：按分辨率分 PC:240x240、APP:240x240
• 版本信息：version_int、build_at、hash、url
• 设备兼容：models 数组（Z042, T020, Z023 等设备型号）
• 平台兼容：iOS/Android/Web 最低版本要求
• 进程列表：容器内需要监控的进程名（用于健康检查）
• 标记位：is_docker=1, is_daemon, remove_able, toggle_able

示例（docker 应用自身的 predefine）：

{
  "app_name": "docker",
  "app_type": "docker",
  "auto_install": 1,
  "auto_upgrade": 1,
  "processes": [
    {"command": "zdocker"},
    {"command": "containerd"},
    {"command": "containerd-shim"},
    {"command": "containerd-shim-runc-v1"},
    {"command": "containerd-shim-runc-v2"},
    {"command": "dockerm"},
    {"command": "docker-proxy"},
    {"command": "docker"},
    {"command": "dockerd"},
    {"command": "docker-init"}
  ]
}

5.3 安装流程

1. PreFlight（前置检查）
   - 检查设备型号是否在支持列表
   - 检查存储池是否就绪
   - 创建应用安装目录（/var/appstore/pkg/<app>/）
   - 创建 appstore_default bridge 网络

2. 下载
   - 从 https://bwcap.zenithspace.net/AppStore/ 下载应用包
   - 包格式：ZIP，含 docker-compose.yml、UI 资源、安装脚本
   - SHA1 校验

3. 安装
   - 解压到安装目录
   - 执行 prepare_install.sh（如有）
   - 写入 app-config.yml、params.json
   - 配置 Nginx 反向代理（/zspace/applications/services/zdocker/config/apps/nginx）
   - 设置 ACL（setfacl）
   - 执行 docker-compose up -d 或 docker run
   - 写入 SQLite apps 表

4. 卸载
   - 执行 prepare_uninstall.sh
   - docker-compose down / docker rm
   - 删除数据目录（可选，由 delete_data 标记控制）
   - 清理 Nginx 配置

5.4 内置推荐镜像

/zspace/applications/services/portainer/image_default.json 预置了 9 个推荐镜像：

六、Android 容器（AIC：Android in Container）

6.1 核心机制

zdocker 最具差异化的功能：在 Docker 容器内运行完整 Android 系统，支持 GPU 加速、HDMI 输出、USB 外设、音频输入输出。

这通过 redroid/TDX（TianDingXing） 技术实现，本质是在容器内运行 Android 的 init 进程，配合宿主机的内核 binder、ashmem、ion 等 Android 子系统。

6.2 关键文件

6.3 容器配置参数

container_common.conf 暴露了 Android 容器的大量硬件配置能力：

# 网络模式：docker0 / macvlan_static / macvlan_dhcp / host
network.type=docker0
net_dns1=114.114.114.114
net_dns2=8.8.8.8

# 显示配置（支持 DSI/HDMI/DPI 等多种接口）
primary_type=DPI-1
default.resolution=1080x1920@60

# 硬件开关
disable.audio.output=true
disable.input.event=false
disable.ueventd.cold_boot=true
disable.usb.configfs=false

6.4 镜像管理

• 基础镜像：tdx_android（Docker 镜像名）
• 镜像包：tiandingxing_android_tdx_android12.img.tar
• 升级服务器：https://aic-images.zenithspace.net/api/upgrade_check
• 差分升级：使用 xdelta3 做差分包，减小下载体积
• SOC 标识：代码中默认 rk3576，但 T2 实际使用 RK3568（可能为未来设备预留）

6.5 云手机功能

zdocker 内部有大量 CloudPhone 相关代码：

• CloudPhone create container %s from image %s
• CloudPhone get random port
• CloudPhoneYunJson —— 云手机配置同步
• 默认云手机端口：3999
• Android 数据目录：/userdata/container/android_data

这说明 Android 容器不仅是本地 HDMI 输出，还预留了远程访问能力（类似云手机/云桌面的体验）。

6.6 实际可用性观察

代码中虽然存在 CloudPhone 模块和默认端口 3999，但实际观察：

• 桌面/移动端 APP 连接设备大概率不走 AIC 通道，而是通过标准的 go-baseset API 网关（:8050/8040）
• 端口 3999 的远程云手机功能在用户侧的实际可用性存疑，可能是预留能力或仅特定型号/场景启用
• AIC 的主要实际用途更可能是 HDMI 本地输出（机顶盒模式），而非远程云手机

七、Docker 兼容性分析

7.1 与标准 Docker 的关系

7.2 启动流程

当用户在 UI 中开启 Docker 功能时：

1. baseset (:8038) 收到 POST /settings docker_do=on
2. 调用 /zspace/applications/services/portainer/shell/start_docker.sh
3. start_docker.sh:
   a. 读取 reghub.json 获取镜像加速器地址
   b. 生成 /etc/docker/daemon.json（data-root, overlay2, ipv6）
   c. 执行 docker_zfsv3_update.sh（数据迁移）
   d. systemctl restart containerd.service
   e. systemctl restart docker.socket
   f. systemctl restart docker.service
   g. 启动 portainer
   h. 调用 baseset/start_d.sh 启动 dockerm
   i. curl -X POST 127.0.0.1:8048/workd start=true
4. zdocker 检测到 Docker Engine 就绪，开始初始化应用商店数据

7.3 安全策略

• seccomp：使用自定义 seccomp 配置文件 /etc/docker/seccomp-copyfail-block.json
• rootless：未实现，所有容器以 root 运行
• IPv6：默认开启，CIDR 为 fd00:db7::/48
• 日志限制：json-file 驱动，单文件 20MB，最多 1 个文件

八、dockerm：C++ 层的 Docker 操作代理

8.1 定位

dockerm 是连接 zdocker（Go 业务层）和 Docker Engine 的操作执行代理。

• 语言：C++（非 Go）
• 大小：4.6 MB
• 框架：cpp-httplib（单头文件 HTTP 库）
• 监听：127.0.0.1:8048

8.2 职责

接收 baseset/zdocker 的 HTTP 请求，调用 shell 脚本完成实际 Docker 操作：

8.3 与 zdocker 的分工

九、Docker 管理界面：Portainer 的三层封装

结论：Portainer + Nginx 反向代理 + Token 认证封装

极空间的 Docker 管理界面底层是开源 Portainer CE，但做了三层封装：

1. Nginx 反向代理 — 用户访问极空间 APP/PC 端 → OpenResty → Nginx proxy_pass → Portainer (:9000)
2. Token 认证桥接 — auth_master.lua 将极空间的用户 token 改写为 Portainer 能理解的 Authorization 头
3. 极空间定制版 — zportainer 可能替换了品牌 logo、默认 endpoint 配置、TLS 证书等

核心原理和 browser 应用（Chrome/Firefox 远程浏览器）一模一样——都是"Docker 容器跑服务，OpenResty 做反向代理 + 认证"。

两个二进制

portainer 的源码路径显示是极空间工程师自行编译集成的（路径形如 /home/<工程师>/portainer/api/...）。

前端技术栈

portainer 前端是一个 AngularJS SPA：

<html lang="en" ng-app="portainer" ng-strict-di>
  <title>Portainer</title>
  <body ng-controller="MainController">
    <div ui-view="sidebar" ...></div>

前端路由（$state）：

• portainer.auth — 登录页
• portainer.init.admin — 初始化管理员
• portainer.init.endpoint — 初始化 endpoint
• portainer.logout — 退出

Portainer API 路由

portainer 暴露的标准 REST API：

集成模式：以 Browser 应用为例

browser 应用（Chrome/Firefox 远程浏览器）展示了极空间如何把 Docker 容器包装成"应用"：

应用定义 (browser_arm.json)：

{
  "name": "Browser",
  "image": "kasmweb/chrome",
  "tag": "1.16.0_zspace_1.8",
  "visit_path": "apps/chrome/",
  "config": {
    "ports": {"56901": "6901"},
    "env": {"KASM_USER_NAME": "admin", "VNC_PW": "Zspace123"}
  }
}

Nginx 反向代理配置 (browser_arm_nginx.conf)：

location /apps/chrome/ {
    access_by_lua_file "$lua_dir/auth_master.lua";  # 极空间 token 认证
    proxy_pass https://127.0.0.1:56901/apps/chrome/;
    proxy_set_header Authorization AUTH_PLACEHOLDER;
}

三步走：

1. Lua 认证 — auth_master.lua 校验用户 token，提取用户身份
2. Token 改写 — 把极空间的用户信息注入 Authorization 头
3. 反向代理 — 把请求转发到容器实际端口

portainer 大概率用同样的方式集成：access_by_lua_file → proxy_pass http://127.0.0.1:9000。

辅助脚本体系

portainer 目录下还有 40+ 个 shell 脚本，是 Docker 操作的后端代理层：

这些脚本由 dockerm（C++ 进程，:8048）调度执行。

运行时容器

container/ 目录下有完整的 containerd 运行时：

所有二进制都是标准的 containerd 包（非自研）。

完整请求链路

用户在极空间 APP 点击"Docker"
    │
    ▼
OpenResty (:80/:5055)
    │ Lua auth_master.lua 校验 token
    ▼
location /abc (或 /docker 路由)
    │ proxy_pass
    ▼
Portainer (:9000)
    │ /api/endpoints/1/docker/...
    ▼
Docker Engine (dockerd, /var/run/docker.sock)
    │
    ▼
containerd → containerd-shim → runc → 容器进程

设备型号差异

启动脚本 docker_start.sh 里有设备型号判断：

• Q2 系列：systemctl stop containerd → 直接禁用 Docker（内存不够）
• Z022 (Z2S Pro)：正常启动 Docker
• Z2S 4G (flag=1)：正常启动 Docker
• T02 (T2)：正常启动 Docker

这解释了为什么"ARM 版本的极空间没有 Docker 管理界面"——T2 上 Docker 引擎默认 inactive，ARM 低端型号更是直接被禁用的。

十、构建与工程推断

10.1 构建环境

• CI：Jenkins（路径 /var/jenkins_home/home/workspace/services/zdocker/）
• Go 版本：1.23.3（设备上共存 4 个 Go 版本，zdocker 锁定 1.23.3）
• Go module 缓存：/home/package-service/source/gowork/pkg/mod/
• 构建服务器：package-service 用户

10.2 版本管理

zdocker 版本号格式：V0.0.1（应用商店元数据中标记为 v0.0.1）

但构建产物的版本号体系遵循极空间统一规范：V0.2.YYYYMMDDNN

10.3 跨平台

zdocker 作为 Go 程序，自然支持交叉编译。从构建脚本看，它随极空间 monorepo 一起为 ARM64（z2/z4）和 AMD64（x86）构建。

十一、与其他 NAS 容器方案的对比

极空间的核心差异化在于把 Docker 完全产品化：应用商店预定义了几十款常用容器应用，一键安装；Android 容器让 NAS 变身机顶盒/云手机；定时任务让用户像设置闹钟一样管理容器。

十二、关键发现汇总

1. zdocker 的 Jenkins 源码路径：/var/jenkins_home/home/workspace/services/zdocker/release/online_t020/
2. Docker SDK 版本：v27.3.1（较新）
3. Android 升级服务器：https://aic-images.zenithspace.net/api/upgrade_check
4. 应用商店 CDN：https://bwcap.zenithspace.net/AppStore/
5. 镜像加速器：https://registry.zenithspace.net（默认）+ https://registry-1.docker.io
6. 云手机默认端口：3999
7. dockerm 是 C++ 写的，不是 Go
8. zdocker 不直接监听端口，通过 baseset/go-baseset 代理
9. 设备型号白名单控制应用兼容性（Z042, T020, Z023 等）
10. 低端型号（Q2）禁用 Docker，内存不足时 containerd 被禁用

附：服务器文件来源（一手资料）