外观

数据存储与备份 ​

首次部署请从安装教程开始。本页说明需要持久保存的目录、数据库选择和备份恢复方法。

准备宿主机目录 ​

/var/lib/zboard/artifacts 下的三类内容使用不同的挂载权限：

  • ZBOARD_ZERO_ARTIFACT_HOST_DIR 保存可信 Zero 程序及校验文件，以只读方式挂载。
  • ZBOARD_MANAGED_RULE_HOST_DIR 保存托管规则源文件和生成的规则产物，以读写方式挂载。
  • ZBOARD_KERNEL_UPLOAD_HOST_DIR（默认 ./kernel-uploads）保存从浏览器上传并校验的内核，以读写方式挂载。重建容器时保留这两个可写目录。

首次部署前执行：

bash
cd deploy/docker
sh ./prepare-host-dirs.sh
mkdir -p ./artifacts/kernel-uploads ./kernel-uploads
chmod 0755 ./artifacts/kernel-uploads
chmod 0750 ./kernel-uploads

自定义位置时，使用与 Compose 相同的环境变量：

bash
export ZBOARD_ZERO_ARTIFACT_HOST_DIR=/srv/zboard/artifacts
export ZBOARD_MANAGED_RULE_HOST_DIR=/srv/zboard/managed-rules
export ZBOARD_KERNEL_UPLOAD_HOST_DIR=/srv/zboard/kernel-uploads
sh ./prepare-host-dirs.sh
mkdir -p "$ZBOARD_ZERO_ARTIFACT_HOST_DIR/kernel-uploads" "$ZBOARD_KERNEL_UPLOAD_HOST_DIR"
chmod 0755 "$ZBOARD_ZERO_ARTIFACT_HOST_DIR/kernel-uploads"
chmod 0750 "$ZBOARD_KERNEL_UPLOAD_HOST_DIR"

MySQL 部署只使用基础 Compose 文件，不创建或挂载 SQLite 数据目录。使用 SQLite 时，设置 ZBOARD_DATABASE_DRIVER=sqlite、ZBOARD_DATA_SOURCE=/var/lib/zboard/data/zboard.db，按需设置 ZBOARD_DATABASE_HOST_DIR，并同时使用 SQLite 覆盖文件：

bash
set -a
. ./.env.release
set +a
sh ./prepare-host-dirs.sh
artifact_dir=${ZBOARD_ZERO_ARTIFACT_HOST_DIR:-./artifacts}
upload_dir=${ZBOARD_KERNEL_UPLOAD_HOST_DIR:-./kernel-uploads}
mkdir -p "$artifact_dir/kernel-uploads" "$upload_dir"
chmod 0755 "$artifact_dir/kernel-uploads"
chmod 0750 "$upload_dir"
docker compose \
  -f docker-compose.release.yml \
  -f docker-compose.sqlite.yml \
  --env-file .env.release \
  up -d

准备脚本会创建 rules/ 挂载点；上面的补充命令准备 kernel-uploads/ 挂载点与独立上传目录。Compose 将两个可写目录分别挂载进去。自定义非 root 容器时，还要让实际服务用户能写入这两个目录。

挂载布局 ​

text
/var/lib/zboard/artifacts                 只读的可信制品目录
├── kernel-uploads                       独立的可写上传内核目录
└── rules                                独立的可写规则目录
    └── <tag>
        ├── source.json                  规范化规则源文件
        └── artifacts/<source-sha256>/   编译后的客户端规则

不要把整个制品目录改成可写。上传内核目录按 SHA-256 复用文件，总容量上限为 1 GiB；它不是自动过期缓存。空间不足时先确认没有待执行或待重试的任务引用旧文件，再清理不用的制品。

直接运行后端时，需把 ZBOARD_ZERO_ARTIFACT_DIR 配为持久目录，并确保其中的 kernel-uploads 可写；未配置制品目录时不能上传内核。

蓝绿部署的两个实例必须共享规则和上传内核目录，否则切换后可能找不到数据库记录或安装任务引用的文件。事件队列仍按部署配置使用各自的目录，不要改成多个写入实例共用一个队列。

备份与恢复 ​

数据库保存规则元数据和修订信息，规则源文件与编译产物保存在 ZBOARD_MANAGED_RULE_HOST_DIR。备份时应在同一备份窗口保存：

  1. 一致的 ZBoard 数据库备份。
  2. 托管规则目录与上传内核目录的归档或快照。
  3. 部署配置、凭据加密密钥及其他持久目录；插件目录的要求见下文。

规则目录备份示例：

bash
managed_rule_dir=${ZBOARD_MANAGED_RULE_HOST_DIR:-./managed-rules}
tar -C "$(dirname "$managed_rule_dir")" \
  -czf "zboard-managed-rules-$(date -u +%Y%m%dT%H%M%SZ).tar.gz" \
  "$(basename "$managed_rule_dir")"

启动恢复后的面板之前，应同时恢复数据库及对应的规则目录。只恢复数据库会缺少规则文件；只恢复目录则可能带回数据库已不再引用的旧修订。

SQLite 的一致性备份与切换步骤见系统维护。

检查部署配置 ​

启动前先检查 Compose 配置：

bash
docker compose -f docker-compose.release.yml --env-file .env.release config --quiet

SQLite 部署需要同时指定两个文件：

bash
docker compose \
  -f docker-compose.release.yml \
  -f docker-compose.sqlite.yml \
  --env-file .env.release \
  config --quiet

启动后检查制品目录只读，规则和上传内核目录可写。以下命令仅创建并删除一个临时检查文件；SQLite 部署需同时加上 SQLite 覆盖文件：

bash
docker compose -f docker-compose.release.yml --env-file .env.release exec zboard sh -c '
  test ! -w /var/lib/zboard/artifacts || exit 1
  touch /var/lib/zboard/artifacts/rules/.write-test
  rm /var/lib/zboard/artifacts/rules/.write-test
  touch /var/lib/zboard/artifacts/kernel-uploads/.write-test
  rm /var/lib/zboard/artifacts/kernel-uploads/.write-test
'

插件数据持久化 ​

服务将 ZBOARD_PLUGIN_HOST_DIR（默认 ./plugins）挂载到 /var/lib/zboard/plugins。prepare-host-dirs.sh 会创建此私有目录。备份时同时保存插件目录、数据库和凭据加密密钥。

需要配置发布者公钥或自定义市场目录时，将配置加入 ZBoard YAML，并以只读方式挂载到 /app/etc/zboard.yaml。具体见插件市场。

同一数据库只能由一个实例执行插件。备用实例可以提供核心接口，但不创建插件页面会话或执行插件操作。切换时停止原实例并重启接替实例；原实例异常退出后需要等待一分钟租约到期。此机制不提供多个实例同时处理插件请求的路由能力。

ZeroDeNet