数据安全柜 Web 端使用说明

适用版本：数据安全柜 1.1.1 及后续兼容版本。

数据安全柜 1.1.1 提供了 Web 端。Web 端并不是独立的业务服务，而是将浏览器操作转换为本机守护进程操作的可视化客户端：安全域、实例、审核和文件操作仍由 dvagentd 完成。

1. 概览与前提条件

Web 端由 dvwebd 网关提供页面和 API；它以低权限的 dvweb 用户运行，浏览器不会直接访问数据盘或内核模块。

使用 Web 端前，请确认：

• 已安装 1.1.1 或更高版本的 datasafebox-cmd-cli 完整软件包；该包应包含 dvwebd、Web 静态页面和 dvweb.service。
• dvagent.service 与 dvweb.service 都可以正常启动。
• 浏览器能够访问登录服务；首次打开 Web 端会自动跳转到典枢登录页。
• 桌面版本机访问无需额外配置（见 3.1）；如需从没有桌面环境的服务器上通过 IP+端口访问，请按第 3.2 节完成 HTTPS 配置。

使用边界：Web 端是部署主机上的可视化客户端，不是供多个不同账号同时共用的中心化 Web 门户。同一 dvagentd 同时只维护一个业务登录身份；其他浏览器或 CLI 使用另一个账号登录后，当前 Web 会话会提示重新登录。

2. 安装、升级与本机访问

2.1 通过 APT 安装或升级

首次安装时，如尚未配置软件源，请先完成软件源配置，然后安装软件包：

sudo apt update
sudo apt install -y datasafebox-cmd-cli

已有旧版本时，升级到包含 Web 端的版本：

sudo apt update
sudo apt install --only-upgrade datasafebox-cmd-cli
dv --version

安装或升级完成后，安装脚本会创建 dvweb 系统用户，并依次启用/重启 dvagent.service 和 dvweb.service。升级会短暂中断 Web 访问，请避开正在进行的关键操作。

本文仅说明 APT 软件包部署。当前没有可直接复用的 Docker/Compose 部署方案，也不建议仅替换 dvwebd 而保留旧版 dvagentd。

2.2 验证服务与页面

在部署主机执行：

test -x /opt/datasafebox-cmd-cli/bin/dvwebd && echo "dvwebd 已安装"
sudo systemctl status dvagent.service dvweb.service --no-pager
curl --noproxy '*' -fsS http://127.0.0.1:8080/api/healthz

健康检查成功时会返回 JSON，其中包含 "ok":true 和 "daemon":"reachable"。若 dvweb.service 不存在或 dvwebd 未安装，请先确认当前软件包版本确为 1.1.1 或更高版本。

默认访问地址为：

http://127.0.0.1:8080/

该地址默认只允许部署主机本机访问。请在部署主机的浏览器中打开它；打开后会自动跳转到三方登录页，登录成功会自动回到数据安全柜首页，无需像命令行登录那样复制授权码。

3. 远程访问与自定义访问链接

Web 端的访问方式取决于 dvwebd 部署在什么样的机器上：

• 部署主机就是你日常使用、已经装有桌面环境和浏览器的 Linux 机器：直接看 3.1，不需要额外配置。
• 部署主机是没有桌面环境的服务器，需要从其他机器的浏览器访问：看 3.2，配置成可通过 IP+端口 直接访问。

3.1 Linux 桌面版：直接通过浏览器访问

dvwebd 默认监听 127.0.0.1:8080。只要浏览器和 dvwebd 运行在同一台机器上，直接打开第 2.2 节的默认链接即可：

http://127.0.0.1:8080/

不需要修改配置，也不需要额外的网络设置。

若默认的 8080 端口和本机其他服务冲突，或想自定义端口，可以直接改端口，不需要启用 HTTPS（因为仍然监听在 127.0.0.1 回环地址上）：

1. 编辑 Web 服务专用配置文件 /var/lib/dvweb/.local/share/dv/config.ini（不是 CLI 用的 /root/.local/share/dv/config.ini），保留已有内容，只新增或修改 [web] 节：

   ini 复制代码

   [web]
   port=8090

2. 重启服务并验证：

   bash 复制代码

   sudo systemctl restart dvweb.service
   curl --noproxy '*' -fsS http://127.0.0.1:8090/api/healthz

3. 在浏览器打开新的地址：

   text 复制代码

   http://127.0.0.1:8090/

只要 listen 仍保持默认的 127.0.0.1（回环地址），改端口不需要配置 TLS 证书，登录回调地址也会自动按新端口推断，无需手动设置 callback_url。

3.2 Server 版：配置 IP+端口直接访问

适用于没有桌面环境、需要其他机器直接通过 https://<服务器IP>:<端口>/ 访问的服务器部署。

出于会话安全考虑，dvwebd 只允许两种监听方式之一：绑定 127.0.0.1（仅本机可访问，见 3.1），或者绑定对外地址并同时启用 TLS——dvwebd 会拒绝在非回环地址上以明文 HTTP 启动。因此“IP+端口”直接访问目前必须启用 HTTPS，下面步骤已经尽量精简。

1. 准备证书目录和私钥（示例路径 /var/lib/dvweb/tls/，私钥只对 dvweb 用户可读）：

   bash 复制代码

   sudo install -d -o root -g dvweb -m 0750 /var/lib/dvweb/tls
   sudo install -o root -g dvweb -m 0644 /path/to/fullchain.pem /var/lib/dvweb/tls/fullchain.pem
   sudo install -o root -g dvweb -m 0640 /path/to/privkey.pem /var/lib/dvweb/tls/privkey.pem

   如果只有服务器 IP、没有域名：大多数 CA 不会给纯 IP 签发证书，可以改用自签名证书（SAN 中需包含该 IP）：

   bash 复制代码

   openssl req -x509 -newkey rsa:2048 -nodes -days 825 \
     -keyout privkey.pem -out fullchain.pem \
     -subj "/CN=<服务器IP>" -addext "subjectAltName=IP:<服务器IP>"

   使用自签名证书时，浏览器会提示“证书不受信任”，需要手动信任该证书才能继续访问。

2. 编辑 Web 服务专用配置文件 /var/lib/dvweb/.local/share/dv/config.ini（不是 CLI 用的 /root/.local/share/dv/config.ini），保留已有内容，只新增或修改 [web] 节，直接用 IP 作为访问地址：

   ini 复制代码

   [web]
   listen=0.0.0.0
   port=8443
   tls_cert=/var/lib/dvweb/tls/fullchain.pem
   tls_key=/var/lib/dvweb/tls/privkey.pem
   callback_url=https://<服务器IP>:8443/api/auth/callback

   保存后确保文件权限正确：

   bash 复制代码

   sudo chown dvweb:dvweb /var/lib/dvweb/.local/share/dv/config.ini
   sudo chmod 0600 /var/lib/dvweb/.local/share/dv/config.ini

3. 重启并验证：

   bash 复制代码

   sudo systemctl restart dvweb.service
   curl --noproxy '*' -fsSk https://<服务器IP>:8443/api/healthz

   然后在浏览器打开 https://<服务器IP>:8443/，并在防火墙或安全组中仅向需要的来源开放该端口。

要点速查：

不要修改 /lib/systemd/system/dvweb.service（或系统对应的 vendor unit 路径）来改端口或地址，软件包升级可能覆盖该文件。

不支持反向代理或子路径部署：Web 前端和 API 固定部署在站点根路径，不能配置为 https://example.com/datasafebox/ 这类子路径访问；请使用独立域名/IP 或独立端口。

4. 登录、导航与功能对应关系

登录成功后，左侧导航列出可访问的安全域、归档安全域、安全域实例和“文件传输”。左侧栏底部的用户菜单可打开消息、关于页面和退出登录。

4.1 创建安全域

1. 在左侧点击“创建安全域”。
2. 填写安全域名称（2～32 个字符，支持中文、英文、数字、_ 和 -）。
3. 选择费用承担方“创建方”或“使用方”，可按需添加可见用户并填写描述。
4. 点击“创建安全域”，随后会进入新安全域详情页。

安全域创建者可管理描述和可见用户、加密文件、审核申请，以及执行停用/移除等管理操作。被添加的可见用户可以查看安全域并申请实例。

4.2 查看安全域、加密文件与审核申请

进入安全域详情页后，可查看基本信息、可见用户、相关实例、应用白名单审核和文件导出审核。创建者可在此页：

• 点击“加密文件至此安全域”，从部署主机选择普通文件并生成 .sealed 加密文件；
• 点击“创建安全域实例”，为安全域申请本机加密存储；
• 审核待处理的实例、应用白名单和文件导出申请；
• 管理可见用户、编辑描述、停用或移除安全域。

“归档/恢复”只改变当前用户左侧列表中的分类，不会关闭安全域或删除数据。停用后，运行中的实例会停止，加密文件无法继续访问；移除安全域属于不可恢复操作，应在确认无保留需求后执行。

4.3 创建、审核与启动安全域实例

在安全域详情页点击“创建安全域实例”，选择实例名称、可用磁盘分区、授权期限，以及可选的初始应用白名单。

高风险操作：所选磁盘或分区将用于 LUKS 加密盘，并会在首次启动实例时初始化/格式化，原有数据不可恢复。 请只选择系统识别为可用、且已完成备份的专用磁盘/分区；不要选择系统盘、已挂载盘或已有业务数据的磁盘。

普通安全域实例的典型状态流转为：

1. 创建后进入“待审核”；
2. 安全域创建者在安全域详情页审核通过后，实例变为“已授权”；
3. 在持有该数据盘的部署主机上点击“启动实例”；
4. 启动成功后实例为“运行中”，并挂载到 /mnt/<实例编号>；
5. 运行中实例才可执行导入、白名单申请和导出申请等数据操作。

典枢安全域实例由后端自动授权并自动启动，不一定经过上述人工审核步骤；请以页面展示的最终状态为准。

实例期限以 UTC+8 的日期解释，截止到所选日期的 23:59:59。页面默认提供 60 天期限，提交前请按实际授权要求调整。

4.4 在运行中实例内导入、导出和管理白名单

打开“运行中”的实例详情页，可以：

• 导入 .sealed 加密文件到实例；
• 提交应用/进程白名单申请。获得批准后，白名单中的程序才可访问实例内数据；
• 提交实例内文件的导出申请；创建者按文件逐项审核；
• 查看实时运行状态和最近的内核拒绝事件；
• 删除实例。

删除正在运行的实例会卸载并格式化其加密盘，数据不可恢复。没有连接该实例数据盘的其他机器仅可查看实例信息，不能启动、导入、导出、修改白名单或删除实例；请回到持有该数据盘的主机操作。

4.5 发送加密文件与接收文件

在“文件传输”页面，或在安全域详情页点击“发送加密文件”，选择部署主机上的 .sealed 文件。系统会生成 6 位取件码，接收方在另一台已安装命令行客户端的机器上执行：

dv transfer recv <6位取件码>

取件码 1 小时内有效且只能使用一次。文件内容通过 WebRTC 点对点传输；信令服务只用于协调连接，不承载文件内容。关闭页面或传输弹窗不会取消任务，如需中止请显式点击“取消传输”。

5. 重要使用与安全提示

5.1 文件选择器操作的是部署主机

Web 页面中的文件选择器和磁盘选择器浏览的是 dvagentd 所在部署主机的文件系统，而不是浏览器所在电脑的文件系统。它不会把浏览器本机文件上传到服务器。

例如，通过服务器版的 IP+端口配置远程访问 Web 端时，导入、加密、发送文件所选择的路径仍必须位于部署主机（而不是打开浏览器的这台电脑）。请先通过符合组织安全要求的方式将文件放到部署主机可访问的目录，再在 Web 页面中选择该路径。

5.2 角色和审核边界

• 安全域创建者负责加密文件、管理可见用户和描述、审核实例/白名单/导出申请，以及停用或移除安全域。
• 安全域使用者主要接收加密文件、申请实例并在获授权后使用实例。
• 页面是否显示按钮只是操作提示，服务端仍会执行身份与状态校验；无权限、实例未运行或安全域已停用时，操作会被拒绝。

5.3 会话、证书和网络边界

• 浏览器会话使用受保护的 Cookie，业务访问令牌不会下发到浏览器；会话约 12 小时后需要重新登录。
• Web 网关使用独立的本地配置和浏览器会话文件，但与 CLI 共用同一个 dvagentd 业务身份。请不要让不同账号在同一部署主机上并发管理同一守护进程。
• 桌面版优先保留默认的 127.0.0.1 回环监听，仅本机访问，如需换端口直接改 port 即可（3.1）；如需 IP+端口直接访问，请启用 HTTPS、使用可信证书或提示用户信任自签名证书，并限制防火墙来源（3.2）。

6. 常见问题

如需进一步排查，请收集以下输出后联系管理员：

sudo systemctl status dvagent.service dvweb.service --no-pager
sudo journalctl -u dvweb.service -n 100 --no-pager