菜单

数据安全柜使用说明

数据安全柜命令行工具（dv）使用说明

注意：以下命令需要 root 权限来执行，建议直接切换到 root 用户后再执行以下命令。

1. 命令结构

bash 复制代码 
dv <子命令组> <操作> [参数] [选项]

根帮助页当前展示的子命令组及其操作：

  • auth：用户认证
    • login：用户登录
    • logout：用户登出
    • whoami：查看当前用户
  • domain：安全域管理
    • create：创建安全域
    • list：查看安全域列表
    • show：查看安全域详情
    • update：更新安全域描述
    • close：关闭安全域
    • add-user：添加可见用户
    • remove-user：移除可见用户
    • encrypt：加密文件至安全域
  • instance：安全域实例管理
    • create：创建安全域实例
    • list：查看实例列表
    • show：查看实例详情
    • start：启动安全域实例
    • delete：删除安全域实例
    • add-whitelist：添加应用白名单
    • remove-whitelist：移除应用白名单
    • import：导入文件至实例
    • export：申请导出文件
  • audit：审核管理
    • list：查看待审核列表
    • instance-detail：查看实例化申请详情
    • instance：审核实例化申请
    • whitelist-detail：查看应用白名单申请详情
    • whitelist：审核应用白名单申请
    • export-detail：查看导出申请详情
    • export：审核导出申请
  • message：消息中心
    • list：查看消息列表
    • show：查看消息详情
    • read：标记消息为已读
    • read-all：标记所有消息为已读
    • delete：删除消息

2. 全局选项

根帮助页当前列出的全局选项：

  • -h, --help：显示帮助信息
  • -v, --version：显示版本信息
  • --format <table|json>：输出格式，默认 table

补充说明：

  • --force 不是通用选项，只在具体动作中生效；当前公开命令里使用它的动作有 dv domain close、dv instance start、dv instance delete、dv message delete
  • --format json 主要影响列表和表格输出；是否支持以具体动作实现为准

3. 通用行为

  • dv auth ... 不要求预先登录
  • 大多数业务命令依赖当前登录态、本地数据库和当前用户 token；是否必须调用后端，以具体动作实现为准
  • 当前稳定身份键是 auth_user_id；展示名优先从本地缓存的 auth_user_name 解析
  • dv domain list 会尽量用后端刷新可访问安全域；刷新不可用时退回本地缓存
  • dv domain show 在有 token 且后端可用时会尝试刷新安全域详情；非安全域创建者会被强制限制为 info 视图
  • dv instance list 默认只展示当前账号创建的实例；若后端不可用或缺少 token，会带警告退回本地缓存
  • dv instance show、dv message list 等动作对后端依赖更强，不能简单等同为“本地只读命令”

4. 用户认证（dv auth）

4.1 用户登录

bash 复制代码 
dv auth login

参数说明：

  • 无额外参数

必要说明：

  • 命令会输出 Casdoor 登录链接，并要求在命令行中输入授权码
  • 如果当前已经登录，会直接提示当前认证用户并返回，不重复发起登录流程
  • 登录成功后，会为当前 auth_user_id 打开对应用户数据库，并把 auth_user_id 写入 ~/.dv/session

示例：

bash 复制代码 
dv auth login

4.2 用户登出

bash 复制代码 
dv auth logout

参数说明：

  • 无额外参数

必要说明：

  • 当前未登录时会提示“当前未登录。”并返回
  • 登出会清空当前 session，并清除当前用户在本地缓存中的 token / refresh token

示例：

bash 复制代码 
dv auth logout

4.3 查看当前用户

bash 复制代码 
dv auth whoami

参数说明：

  • 无额外参数

必要说明：

  • 当前实现输出认证用户名、认证用户 ID 和一行当前时间信息
  • 若当前未登录，会提示使用 dv auth login 登录

示例：

bash 复制代码 
dv auth whoami

5. 安全域管理（dv domain）

5.1 创建安全域

bash 复制代码 
dv domain create -n <名称> --payer <创建者|使用者> [--desc <描述>] [--users <u1,u2>]

参数说明：

  • -n, --name <名称>：安全域名称，必填，长度 2 到 32，仅支持中文、英文、数字、_、-
  • --payer <创建者|使用者>：费用承担方，必填
  • --desc <描述>：安全域描述，可选，最多 500 个字符
  • --description <描述>：--desc 的别名
  • --users <u1,u2>：可见用户列表，逗号分隔

必要说明：

  • 创建时会生成安全域密钥对
  • 若启用了后端接口，会调用后端创建安全域，并将详情回写本地缓存
  • 同名安全域会报错

示例：

bash 复制代码 
dv domain create -n "研发数据域" --payer 创建者 --desc "研发敏感数据" --users alice,bob

5.2 查看安全域列表

bash 复制代码 
dv domain list [--status <running|closed>] [--format <table|json>]

参数说明：

  • --status <running|closed>：按状态筛选
  • --format <table|json>：输出格式

必要说明：

  • 列表会展示“我创建的安全域”和“他人创建但共享给我的安全域”
  • 有 token 且后端可用时，会尝试用 /api/domain/list 刷新当前可访问安全域及其状态
  • 后端刷新不可用时，会退回本地缓存

示例：

bash 复制代码 
dv domain list --status running

5.3 查看安全域详情

bash 复制代码 
dv domain show <安全域名称|安全域编号|公钥> [--section <info|users|instances|whitelist|exports|all>]

参数说明：

  • <安全域名称|安全域编号|公钥>：安全域标识，必填
  • --section <info|users|instances|whitelist|exports|all>：仅显示指定部分，默认 all

必要说明：

  • info：基本信息
  • users：可见用户列表
  • instances：安全域实例列表
  • whitelist：应用白名单申请列表
  • exports：文件导出申请列表
  • 有 token 且后端可用时，命令会先尝试刷新安全域详情；创建者查看 instances、whitelist、exports 时还会继续同步相关后端列表
  • 非安全域创建者会被强制限制为 info 视图，不能查看 users、instances、whitelist、exports

示例：

bash 复制代码 
dv domain show "研发数据域" --section whitelist

5.4 更新安全域描述

bash 复制代码 
dv domain update <安全域名称|安全域编号|公钥> --desc <描述>

参数说明：

  • <安全域名称|安全域编号|公钥>：安全域标识，必填
  • --desc <描述>：安全域描述，必填，最多 500 个字符
  • --description <描述>：--desc 的别名

必要说明：

  • 仅安全域创建者可更新描述
  • 描述不能为空，且不能是纯空白内容
  • 已关闭的安全域不能再更新描述

示例：

bash 复制代码 
dv domain update "研发数据域" --desc "更新后的描述"

5.5 关闭安全域

bash 复制代码 
dv domain close <安全域名称|安全域编号|公钥> [--force]

参数说明：

  • <安全域名称|安全域编号|公钥>：安全域标识，必填
  • --force：跳过确认提示

必要说明：

  • 仅安全域创建者可关闭安全域
  • 默认会弹出确认提示；使用 --force 时直接执行
  • 关闭安全域后，相关实例会停止，加密文件无法继续访问

示例：

bash 复制代码 
dv domain close "研发数据域" --force

5.6 添加可见用户

bash 复制代码 
dv domain add-user <安全域名称|安全域编号|公钥> -u <用户账号>

参数说明：

  • <安全域名称|安全域编号|公钥>：安全域标识，必填
  • -u, --user <用户账号>：要添加的用户账号，必填

必要说明：

  • 仅安全域创建者可添加可见用户
  • 已关闭的安全域不能再添加可见用户
  • 命令会把输入解析为目标用户的 auth_user_id，再写入可见用户列表

示例：

bash 复制代码 
dv domain add-user "研发数据域" -u alice

5.7 移除可见用户

bash 复制代码 
dv domain remove-user <安全域名称|安全域编号|公钥> -u <用户账号>

参数说明：

  • <安全域名称|安全域编号|公钥>：安全域标识，必填
  • -u, --user <用户账号>：要移除的用户账号，必填

必要说明：

  • 仅安全域创建者可移除可见用户
  • 已关闭的安全域不能再移除可见用户
  • 删除时既支持直接传 auth_user_id，也支持基于本地用户缓存解析用户名；若命中多个同名用户会报错

示例：

bash 复制代码 
dv domain remove-user "研发数据域" -u alice

5.8 加密文件至安全域

bash 复制代码 
dv domain encrypt <安全域名称|安全域编号|公钥> -f <文件路径> [-o <输出路径>]

参数说明：

  • <安全域名称|安全域编号|公钥>：安全域标识，必填
  • -f, --file <文件路径>：要加密的文件路径，必填
  • -o, --output <输出路径>：输出路径，可选，默认在原文件名后追加 .sealed

必要说明：

  • 文件必须存在
  • 安全域必须处于“运行中”状态
  • 当前实现会显示进度条，并将文件加密到目标安全域公钥下

示例：

bash 复制代码 
dv domain encrypt "研发数据域" -f /data/report.xlsx -o /data/report.xlsx.sealed

6. 安全域实例管理（dv instance）

6.1 创建安全域实例

bash 复制代码 
dv instance create -d <安全域名称|安全域编号|公钥> -n <实例名称> --disk <挂载点> [--whitelist <路径>]

参数说明：

  • -d, --domain <安全域名称|安全域编号|公钥>：所属安全域，必填
  • -n, --name <名称>：实例名称，必填
  • --disk <挂载点>：独立磁盘分区挂载点，必填
  • --whitelist <路径>：应用白名单主程序路径，可选

必要说明：

  • --disk 必须是独立磁盘分区的挂载点，不能是某个分区下的普通子目录
  • --whitelist 当前只支持单个主程序路径
  • 创建前会校验安全域状态、磁盘分区信息、卷占用情况和白名单文件列表

示例：

bash 复制代码 
dv instance create -d "研发数据域" -n "开发实例1" --disk /data/safebox --whitelist /usr/bin/ls

6.2 查看实例列表

bash 复制代码 
dv instance list [-d <安全域>] [--status <pending|authorized|rejected|running|expired|closed>] [--format <table|json>]

参数说明：

  • -d, --domain <安全域>：按安全域筛选
  • --status <pending|authorized|rejected|running|expired|closed>：按实例状态筛选
  • --format <table|json>：输出格式

必要说明：

  • 默认只展示当前账号创建的安全域实例
  • 当前实现支持的状态筛选值为 pending、authorized、rejected、running、expired、closed
  • 若后端不可用或缺少 token，会告警并退回本地实例缓存

示例：

bash 复制代码 
dv instance list --status authorized

6.3 查看实例详情

bash 复制代码 
dv instance show <实例名称或编号> [--section <info|whitelist|exports|all>]

参数说明：

  • <实例名称或编号>：实例标识，必填
  • --section <info|whitelist|exports|all>：只显示指定部分，默认 all

必要说明：

  • 当前实现会调用后端 /api/instance/detail 刷新实例状态；后端接口不可用或缺少 token 时会直接失败
  • whitelist 显示应用白名单申请记录
  • exports 显示文件导出申请记录
  • 当 section 为 all、whitelist 或 exports 时，命令会自动提交尚未提交过的已授权申请到内核
  • 应用白名单申请按申请编号自动提交；文件导出申请按 申请编号 + 文件编号 自动提交
  • 自动提交后会输出本次验证成功和失败的授权列表，不回显已跳过的历史项
  • section=info 仅显示基本信息，不触发自动提交

示例：

bash 复制代码 
dv instance show "开发实例1" --section exports

6.4 启动安全域实例

bash 复制代码 
dv instance start <实例名称或编号> [--force]

参数说明：

  • <实例名称或编号>：实例标识，必填
  • --force：跳过确认提示

必要说明：

  • 只有实例创建者才能启动实例
  • 只有状态为“已授权”的实例才能启动
  • 默认会显示启动确认信息；使用 --force 时跳过确认
  • 启动时会调用后端 /api/instance/detail 获取 encryptedDomainPriKey
  • encryptedDomainPriKey 会在内存中解密为安全域私钥，不会写回本地数据库
  • 若实例详情缺少 encryptedDomainPriKey，启动会直接失败
  • 启动会先向 trammel 内核注册安全域，再调用后端 /api/instance/run

示例：

bash 复制代码 
dv instance start "开发实例1" --force

6.5 删除安全域实例

bash 复制代码 
dv instance delete <实例名称或编号> [--force]

参数说明：

  • <实例名称或编号>：实例标识，必填
  • --force：跳过删除确认；若实例处于运行中，仍需输入设备路径确认格式化

必要说明：

  • 只有实例创建者才能删除实例
  • 运行中的实例会卸载并格式化对应块设备；非运行中的实例只删除实例记录，不格式化磁盘
  • 只有删除运行中实例时，才要求实例路径对应独立块设备挂载点
  • 默认会要求确认删除实例；运行中实例还会额外警告“实例内所有数据将无法恢复”
  • 只有删除运行中实例时，才会额外要求输入待格式化设备路径；只有输入内容与提示的设备路径完全一致时，才会继续卸载并执行 mkfs.ext4
  • 使用 --force 时，如果后端删除成功但本地卸载、格式化或内核清理失败，实例记录仍会删除，并输出残留警告

示例：

bash 复制代码 
dv instance delete "开发实例1" --force

6.6 添加应用白名单

bash 复制代码 
dv instance add-whitelist <实例名称或编号> -p <应用路径> [--reason <申请原因>]

参数说明：

  • <实例名称或编号>：实例标识，必填
  • -p, --path <应用路径>：要添加的应用路径，必填
  • --reason <申请原因>：申请原因，可选，最多 500 个字符

必要说明：

  • 只有实例创建者才能修改应用白名单
  • 实例必须处于“运行中”状态
  • 目标文件必须存在

示例：

bash 复制代码 
dv instance add-whitelist "开发实例1" --path /usr/bin/python3 --reason "研发脚本执行"

6.7 移除应用白名单

bash 复制代码 
dv instance remove-whitelist <实例名称或编号> -p <应用路径或名称>

参数说明：

  • <实例名称或编号>：实例标识，必填
  • -p, --path <应用路径或名称>：要移除的应用路径或名称，必填

必要说明：

  • 只有实例创建者才能修改应用白名单
  • 实例必须处于“运行中”状态
  • 既支持按完整路径移除，也支持按名称匹配移除

示例：

bash 复制代码 
dv instance remove-whitelist "开发实例1" --path python3

6.8 导入文件至实例

bash 复制代码 
dv instance import <实例名称或编号> -f <文件路径>

参数说明：

  • <实例名称或编号>：实例标识，必填
  • -f, --file <文件路径>：要导入的文件路径，必填

必要说明：

  • 实例必须处于“运行中”状态
  • 当前实现一次只读取一个 -f/--file 值；动作帮助中的多 -f 示例不代表稳定支持一次导入多个文件
  • 如果文件名以 .sealed 结尾，会先解密再导入；否则直接复制到实例路径

示例：

bash 复制代码 
dv instance import "开发实例1" -f /tmp/report.xlsx.sealed

6.9 申请导出文件

bash 复制代码 
dv instance export <实例名称或编号> -f <文件路径列表> [--reason <导出原因>]

参数说明：

  • <实例名称或编号>：实例标识，必填
  • -f, --files <文件路径列表>：要导出的文件列表，必填
  • --reason <导出原因>：导出原因，可选，最多 500 个字符

必要说明：

  • 实例必须处于“运行中”状态
  • 当前实现从单个选项值中解析文件列表，多个路径使用逗号分隔，例如 -f "/a,/b" 或 --files "/a,/b"
  • 当前解析器不会把多次重复传入的 -f/--files 合并为一个稳定的文件列表
  • 导出文件必须位于该安全域实例路径下；若存在不合规路径，命令会失败并列出全部不合规项
  • 导出申请提交后需要安全域创建者审核

示例：

bash 复制代码 
dv instance export "开发实例1" --files "/data/report.pdf,/data/result.csv" --reason "项目汇报"

7. 审核管理（dv audit）

7.1 查看待审核列表

bash 复制代码 
dv audit list [--type <instance|whitelist|export|all>] [--domain <安全域>]

参数说明：

  • --type <instance|whitelist|export|all>：审核类型，默认 all
  • --domain <安全域>：按安全域筛选

必要说明：

  • instance：实例化申请
  • whitelist：应用白名单申请
  • export：文件导出申请
  • 若后端可用且 token 完整，命令会先同步待审核数据，再从本地数据库汇总展示

示例：

bash 复制代码 
dv audit list --type whitelist

7.2 查看实例化申请详情

bash 复制代码 
dv audit instance-detail <实例编号>

必要说明：

  • 只有安全域创建者可查看对应实例的审核详情

示例：

bash 复制代码 
dv audit instance-detail I17726096359687372

7.3 审核实例化申请

bash 复制代码 
dv audit instance <实例编号> --action <approve|reject>

参数说明：

  • --action <approve|reject>：审核动作，必填

必要说明：

  • 只有安全域创建者才能审核实例化申请
  • 实例必须处于“待审核”状态
  • 已关闭的安全域不能继续审核其实例化申请

示例：

bash 复制代码 
dv audit instance I17726096359687372 --action approve

7.4 查看应用白名单申请详情

bash 复制代码 
dv audit whitelist-detail <申请编号>

示例：

bash 复制代码 
dv audit whitelist-detail A17736720770637258

7.5 审核应用白名单申请

bash 复制代码 
dv audit whitelist <申请编号> --action <approve|reject>

参数说明：

  • --action <approve|reject>：审核动作，必填

必要说明：

  • 只有安全域创建者才能审核应用白名单申请
  • 已关闭的安全域不能继续审核应用白名单申请

示例：

bash 复制代码 
dv audit whitelist A17736720770637258 --action reject

7.6 查看导出申请详情

bash 复制代码 
dv audit export-detail <申请编号> --file-code <文件编号>

参数说明：

  • --file-code <文件编号>：指定要查看的文件编号，必填

必要说明：

  • 详情是按“申请编号 + 文件编号”定位的单个导出文件项

示例：

bash 复制代码 
dv audit export-detail A17735869339174558 --file-code F17735869339170001

7.7 审核导出申请

bash 复制代码 
dv audit export <申请编号> --file-code <文件编号> --action <approve|reject>

参数说明：

  • --file-code <文件编号>：指定要审核的文件编号，必填
  • --action <approve|reject>：审核动作，必填

必要说明：

  • 审核粒度是单个导出文件项，而不是整条申请记录
  • 已关闭的安全域不能继续审核导出申请
  • 通过审核时，命令会基于安全域私钥为目标文件生成 approveSign

示例：

bash 复制代码 
dv audit export A17735869339174558 --file-code F17735869339170001 --action approve

8. 消息中心（dv message）

8.1 查看消息列表

bash 复制代码 
dv message list [--filter <all|unread>] [--page <页码>] [--size <每页数量>] [--format <table|json>]

参数说明：

  • --filter <all|unread>：过滤条件，默认 all
  • --page <页码>：页码，默认 1
  • --size <每页数量>：每页数量，默认 10
  • --format <table|json>：输出格式

必要说明：

  • 当前实现直接调用后端消息列表接口显示结果
  • unread 仅显示未读消息
  • 当前页中符合条件的已授权应用白名单消息和文件导出消息会自动提交到内核，并输出成功/失败汇总
  • 若当前页包含未读的实例审核通过消息，且本地缓存中存在对应实例并且尚未运行，输出末尾会追加实例启动提醒

示例：

bash 复制代码 
dv message list --filter unread --format json

8.2 查看消息详情

bash 复制代码 
dv message show <消息编号>

必要说明：

  • 详情内容来自当前用户本地消息表
  • 若消息符合条件，会在展示详情时自动提交已授权应用白名单/文件导出项到内核
  • 查看详情后，如果消息原本未读，会自动标记为已读

示例：

bash 复制代码 
dv message show M17726119432052285

8.3 标记消息为已读

bash 复制代码 
dv message read <消息编号>

必要说明：

  • 若消息已经是已读状态，会直接提示并返回

示例：

bash 复制代码 
dv message read M17726119432052285

8.4 标记所有消息为已读

bash 复制代码 
dv message read-all

必要说明：

  • 会逐条尝试同步后端已读状态，并更新本地消息表

示例：

bash 复制代码 
dv message read-all

8.5 删除消息

bash 复制代码 
dv message delete <消息编号> [--force]

参数说明：

  • --force：跳过确认提示

必要说明：

  • 默认会要求确认；使用 --force 时直接删除

示例：

bash 复制代码 
dv message delete M17726119432052285 --force

9. 常见返回码

以下返回码是当前实现中的常见语义，不是所有命令共享的严格全局枚举：

  • 0：成功
  • 1：一般错误、后端错误、数据库错误，或未知命令组
  • 2：参数错误、输入校验失败，或未知操作
  • 3：未登录
  • 4：权限不足
  • 5：资源不存在
  • 6：资源冲突或已存在
  • 7：当前状态不允许执行该操作
  • 9：文件相关错误
最近修改: 2026-05-21