thorpejosh/truenas-zfs-unlock

TrueNAS ZFS加密密钥自主管理与远程解锁工具

https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/test.yml/badge.svg](https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/test.yml) https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/docker-publish.yml/badge.svg](https://github.com/ThorpeJosh/truenas-zfs-unlock/actions/workflows/docker-publish.yml) ![pre-commit.ci status]([***]

镜像概述和主要用途

本工具通过支持密钥异地存储、远程数据集解锁和自主控制解锁时机，让您完全掌控TrueNAS ZFS加密密钥。解决了TrueNAS默认将ZFS数据集加密密钥存储在启动盘的安全隐患，确保密钥不与加密驱动器物理共存，提升数据在运输、失窃等场景下的安全性。

核心功能和特性

• 密钥自主管理：避免密钥本地存储，支持外部安全存储
• 远程解锁：通过TrueNAS API远程解锁加密数据集
• 定时控制：支持基于 cron 表达式的定时解锁策略
• 多架构支持：兼容多种硬件架构，部署灵活
• 安全配置：支持通过Docker Secrets管理敏感密钥信息
• SSL/TLS选项：可配置跳过证书验证，适应自签名证书环境

使用场景和适用范围

• 物理安全增强：保护硬件驱动器在静止、运输、处置或失窃时的数据安全
• 远程管理：从异地设备（云服务器、树莓派、笔记本等）控制TrueNAS数据集解锁
• 自动化部署：配合TrueNAS启动流程，在VM或Kubernetes部署前自动解锁数据集
• 多环境兼容：适用于家庭实验室、企业存储系统等多种场景

镜像变体

支持的架构

!Architecture !Architecture !Architecture !Architecture !Architecture !Architecture !Architecture

共享标签

• latest：最新版本
• ${IMAGE_VERSION}：特定版本号（推荐生产环境使用）

注意：镜像采用语义化版本格式发布。TrueNAS在25.04和25.10版本间对API进行了重大变更，使用前请参考发布说明确保兼容性。生产环境中应避免使用latest标签，建议锁定至具体版本。

镜像仓库

该镜像同时发布于https://hub.docker.com/r/thorpejosh/truenas-zfs-unlock%E5%92%8Chttps://github.com/ThorpeJosh/ssh-agent-docker/pkgs/container/truenas-zfs-unlock%EF%BC%8C%E5%8F%AF%E9%80%9A%E8%BF%87%E4%BB%A5%E4%B8%8B%E5%91%BD%E4%BB%A4%E6%8B%89%E5%8F%96%EF%BC%9A

shell
docker pull thorpejosh/truenas-zfs-unlock:latest
docker pull ghcr.io/thorpejosh/truenas-zfs-unlock:latest

使用方法和配置说明

前置准备

1. 将ZFS数据集配置为"Passphrase"加密模式，手动设置密钥（避免TrueNAS存储密钥）
2. 在TrueNAS Web UI中生成API密钥（用于工具通过API发送解锁请求）

环境变量配置

从文件读取环境变量（Docker Secrets）

通过在环境变量名前添加FILE__前缀，可从文件中读取敏感配置。例如：

• 若密钥存储在/run/secrets/dataset_key文件中，可设置FILE__ZFS__pool__dataset=/run/secrets/dataset_key

按需运行（手动解锁）

通过覆盖容器入口命令为unlock，手动触发数据集解锁。

docker-compose配置

yaml
---
services:
  truenas_unlock:
    image: thorpejosh/truenas-zfs-unlock:latest
    environment:
      - TRUENAS_HOST=10.0.0.1:443
      - TRUENAS_API_KEY=1-5x23jkKKsy
      - SKIP_CERT_VERIFY=true
      - ZFS__tank__photos=SomeSecureKey
    command: unlock

docker run命令

shell
docker run --rm \
    -e TRUENAS_HOST=10.0.0.1:443 \
    -e TRUENAS_API_KEY=1-5x23jkKKsy \
    -e SKIP_CERT_VERIFY=true \
    -e ZFS__tank__photos=SomeSecureKey \
    thorpejosh/truenas-zfs-unlock:latest unlock

定时运行（自动解锁）

配置CRONTAB环境变量实现定时解锁（如每10秒检查一次，确保TrueNAS启动后自动解锁数据集）。

docker-compose配置

yaml
---
services:
  truenas_unlock:
    image: thorpejosh/truenas-zfs-unlock:latest
    environment:
      - TZ=America/Chicago
      - TRUENAS_HOST=10.0.0.1:443
      - TRUENAS_API_KEY=1-5x23jkKKsy
      - SKIP_CERT_VERIFY=true
      - ZFS__tank__home=someRandomGeneratedKey
      - ZFS__tank__photos=SomeSecureKey
      # supercronic支持vixie cron表达式：秒 分 时 日 月 周 年 命令
      - CRONTAB=*/10 * * * * * * unlock
    restart: unless-stopped

docker-compose使用Docker Secrets

yaml
---
secrets:
  TRUENAS_API_KEY:
    file: ${PWD}/.secrets/.api_key
  ZFS_HOME_KEY:
    file: ${PWD}/.secrets/.home_key
  ZFS_PHOTOS_KEY:
    file: ${PWD}/.secrets/.photos_key

services:
  truenas_unlock:
    image: thorpejosh/truenas-zfs-unlock:latest
    secrets:
      - TRUENAS_API_KEY
      - ZFS_HOME_KEY
      - ZFS_PHOTOS_KEY
    environment:
      - TZ=America/Chicago
      - TRUENAS_HOST=10.0.0.1:443
      - SKIP_CERT_VERIFY=true
      - FILE__TRUENAS_API_KEY=/run/secrets/TRUENAS_API_KEY
      - FILE__ZFS__tank__home=/run/secrets/ZFS_HOME_KEY
      - FILE__ZFS__tank__photos=/run/secrets/ZFS_PHOTOS_KEY
      # supercronic支持vixie cron表达式：秒 分 时 日 月 周 年 命令
      - CRONTAB=*/10 * * * * * * unlock
    restart: unless-stopped