DataBrain 用户手册

01软硬件需求

DataBrain 以单个 Docker 镜像交付，启动自动探测硬件选档，无需手动调参。

1. 基础前置

GPU 模式另需：NVIDIA 显卡驱动（内核模块）+ NVIDIA Container Toolkit。CPU 模式可跳过。

Docker 安装示例（仅当主机尚未安装 Docker 时）

Ubuntu / Debian：

sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER   # 重新登录生效

CentOS / RHEL / Rocky / Alma 8（CentOS 8 已 EOL，需 vault 重定向 + 解 runc 冲突 + SELinux 放宽）：

sudo sed -i -e 's|^mirrorlist=|#mirrorlist=|' -e 's|^#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|' /etc/yum.repos.d/CentOS-*.repo
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y --allowerasing docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo setenforce 0 || true; sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
sudo usermod -aG docker $USER; sudo systemctl enable --now docker

GPU：装完 Docker 后再装 nvidia-container-toolkit（Ubuntu apt / RHEL dnf），然后 sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker。

2. 推荐配置

启动按显存自动选档：≥ 8 GB → GPU-大档；有 GPU 但 < 8 GB → GPU-小档；无 GPU → CPU。三档准确性一致，仅速度不同（CPU 约为 GPU 的 1/19–1/33）。当前档位见日志 profile=…。

3. 端口

改端口：安装时 DATABRAIN_PORT=<端口> bash <databrain>.sp，或改 docker-compose.prod.yml 的 ports。

02安装与启动

.sp 是自解压安装包：bash <文件>.sp 一条命令完成加载、探测 CPU/GPU、启动、健康门禁、样例验证。

两个包（文件名以实际交付为准，可能是 siipulse-beta_* 测试版）：

• siipulse-rel_baseimage_1.0.sp（~2.9 GB）：共享 Docker 依赖基座，每机装一次，被所有版本 / 产品复用。
• siipulse-rel_databrain_<ver>.sp（~0.7 GB）：应用包，每版本重发。版本号 = 镜像 tag = 文件名末尾数字。

快速开始

# 0) 一次性主机预备（需 sudo；创建安装目录 + 放行防火墙 18000/18001）
sudo bash siipulse-rel_databrain_<ver>.sp --prepare-host

# 1) 安装（进入第 0 步创建的安装目录，路径见其输出；两个 .sp 放入该目录，应用包自动先装 BaseImage，再启动服务）
cd <安装目录>
bash siipulse-rel_databrain_<ver>.sp

# 2) 激活 License（首装会打印机器码，报给厂商换 license.json）
bash databrain-ops.sh fingerprint
bash databrain-ops.sh activate license.json

# 3) 确认就绪 + 第一次扫描
bash databrain-ops.sh status
curl -X POST http://127.0.0.1:18000/v1/text/scan -H 'Content-Type: application/json' \
  -d '{"text":"联系人张伟，邮箱 zhangwei@google.com，手机 +86 13800138000。"}'

升级 / 回滚

bash siipulse-rel_databrain_<新版本>.sp  # 安装包直装：自动复用本机已装的 BaseImage；失败自动回滚上一版
bash databrain-ops.sh upgrade <新版本>   # 镜像已就位时的安全原地升级（多步守卫，任一失败自动回滚）
bash databrain-ops.sh revert             # 撤销最近一次升级

License 在 license/ 卷，升级不触碰，无需重新激活。

License（离线授权）

DataBrain 采用离线授权。扫描类接口（/v1/text/scan、/v1/values/scan）需先激活 License，否则返回 403 license_required；/v1/health、/v1/license/status 始终开放。

激活（命令见上方“快速开始”第 2 步）：采集本机机器码 → 报给奇点律动换取 license.json → 装入激活即可。

• License 与本机绑定；同一台机器上的升级、重启、容器重建无需重新激活。
• 更换主机或迁移到其他机器时，需在新机上重新采集机器码、重新换发 License。
• 验证：curl http://127.0.0.1:18000/v1/license/status 应返回 valid:true。

管理控制台（端口 18001，HTTPS）

容器启动后同机监听 https://<主机>:18001/（默认 admin/admin，首次登录提示改密），与推理 API 共用同一 License。控制台提供：

• 仪表盘：运行概览与核心指标。
• 系统管理：系统状态 / License 导入 / .sp 版本管理 / 重启。
• 自学习：新类型发现与语料包管理。
• Playground：在线试扫。
• 审计：检测日志查阅 / 人工标注 / 统计与跳页。
• 故障排查：诊断打包。
• 顶部健康告警：常驻状态横幅。

HTTPS 说明（2026-08-21 起默认开启）

• 证书机制：控制台以原生 TLS 提供服务，证书为首启自动生成的自签证书（ECDSA P-256，有效期 10 年，SAN 含本机 IP + localhost，由安装器写入 .env 的 DATABRAIN_TLS_HOST_IP 决定）。
• 首次访问告警：私网 IP 无法取得公共 CA 签名，浏览器会提示"您的连接不是私密连接"——点 高级 → 继续前往 即可。
• 证书持久化：证书存于 console-data/ 卷，容器升级/重建不换证书，无需重复信任。
• 彻底消除告警：将 console-data/tls/console.crt（容器内 /app/webui/tls/console.crt）导入操作系统/企业证书信任库。
• 退回 HTTP：.env 中 DATABRAIN_CONSOLE_TLS=0（仅建议本地调试）。
• 公网部署：仍建议前置 nginx 终止 TLS（换正式域名证书）+ IP 白名单。

运维命令（databrain-ops.sh）

start | stop | restart | status | logs -f | health | license | verify | fingerprint | activate <file> | upgrade <ver> | rollback <ver> | revert | clear | deps | diagnose | version

任意目录可用：将安装目录加入 PATH（export PATH=<安装目录>:$PATH）。更多排障见 07-运维与故障排查，返回字段语义见 03-API 集成指南。

常见问题

ops-agent（可选 · WebUI 远程升级 / 重启）

装上后控制台“系统管理”可经本机安全通道远程触发重启与 .sp 版本升级（容器重建期间约 30–90s 不可用，失败自动回滚）。每机一次（app 须已先 install）：

sudo bash siipulse-rel_databrain_<ver>.sp --install-ops-agent

03API 集成指南

DataBrain 以 HTTP 接口对外提供敏感数据发现能力，按数据形态选择集成路径：

每条判定结果均附带判定溯源字段（method / role，始终返回）与可选判定证据（evidence，按需返回），使每一次判定可追溯、可审计。字段语义见第 3 节。

1. 文档级扫描 POST /v1/text/scan

适用于非结构化自由文本。引擎在一篇文本中定位全部敏感实体，返回类型、字符坐标、置信度与判定溯源。

1. 健康检查

GET /v1/health

{"status":"ok","ready":true}

2. 敏感数据扫描

POST /v1/text/scan
Content-Type: application/json

{
  "text": "待扫描文本（1–100,000 字符）",
  "min_confidence": 0.5,
  "return_evidence": false
}

请求参数

响应

{
  "results": [
    {
      "value": "zhangwei@example.com",
      "pii_type": "EMAIL",
      "start": 11,
      "end": 31,
      "confidence": 0.99,
      "needs_review": false,
      "method": "truth_table",
      "role": "reference"
    }
  ]
}

错误码

2. 值级批量分类 POST /v1/values/scan

适用于扫描数据库表、CSV / Excel 列、数据湖字段等结构化列值。以"一批值"为单位，每个值独立判定并返回置信度。

POST /v1/values/scan
Content-Type: application/json

{
  "values": [
    {"value": "zhangwei@example.com", "value_id": "r1", "label_hint": "email"},
    {"value": "110101199003077334", "value_id": "r2", "label_hint": "id_card"},
    {"value": "13800138000", "value_id": "r3", "container_path": "customer.phone"}
  ],
  "return_evidence": false
}

请求参数

响应

{
  "results": [
    {"value_id": "r1", "value": "zhangwei@example.com", "pii_type": "EMAIL",   "confidence": 0.99, "needs_review": false, "is_mock": false, "method": "truth_table", "role": "subject"},
    {"value_id": "r2", "value": "110101199003077334",    "pii_type": "ID_CARD", "confidence": 0.92, "needs_review": false, "is_mock": false, "method": "truth_table", "role": "identifier"}
  ]
}

错误码

3. 判定溯源字段（method / role / evidence）

DataBrain 的每一次判定都附带溯源信息，使判定过程透明、可验证、可审计——而非黑盒输出。

method — 判定路径

标识该条结果由引擎哪条路径得出，反映判定所依据的信号强度与置信度分层：

role — 语义角色

由列名 / 字段名（label_hint）推断该值在业务中的语义角色，辅助下游策略决策：

evidence — 判定证据（按需返回）

evidence 默认不返回，仅在请求 return_evidence=true 时附带。它承载支撑该次判定的客观证据，例如：

4. label_hint 说明（值级独有）

label_hint 是请求中传入的列名 / 字段名提示（如 email、id_card、passport）。它是辅助引擎判定的强线索，尤其在纯数字、格式相近的标识符上显著提升准确率（如身份证号 vs 护照号 vs 社保号）。

• 传入方式：在 values[] 每个对象中设置 label_hint 字段；
• 未传 label_hint 时，系统自动从 container_path 的末段派生（如 customer.phone→phone、users.email→email）—— 因此只要把真实的列名 / 字段名填进 container_path，即可获得与显式 label_hint 相同的增益，无需重复填写；
• 列名命中已知类型词（如 phone / email / ssn / id_card / passport / dob）时才生效；无意义列名（如 col_0、value1）会被安全忽略，不影响判定结果；
• 显式 label_hint 永远优先；两者都不传时，引擎仍可正常判定；
• 生产建议：数据库字段名、CSV 表头天然构成高质量列名提示，推荐经 container_path 或 label_hint 传入。

5. 完整调用示例

curl

curl -X POST http://127.0.0.1:18000/v1/text/scan \
  -H 'Content-Type: application/json' \
  -d '{"text":"订单 #A12345，客户 john.doe@google.com，电话 +1-415-555-0142。","min_confidence":0.5}'

Python（HTTP）

import requests

resp = requests.post(
    "http://127.0.0.1:18000/v1/text/scan",
    json={"text": "客户 john.doe@google.com，电话 +1-415-555-0142。", "min_confidence": 0.5},
    timeout=30,
)
for m in resp.json()["results"]:
    print(m["pii_type"], m["value"], m["confidence"], m["method"])

Java

// 使用 JDK 11+ HttpClient
import java.net.http.*;
import java.net.URI;

var body = "{\"text\":\"客户 john.doe@google.com，电话 +1-415-555-0142。\",\"min_confidence\":0.5}";
var req = HttpRequest.newBuilder()
    .uri(URI.create("http://127.0.0.1:18000/v1/text/scan"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

C# (.NET)

using var http = new HttpClient();
var body = """{"text":"客户 john.doe@google.com，电话 +1-415-555-0142。","min_confidence":0.5}""";
var content = new StringContent(body, System.Text.Encoding.UTF8, "application/json");
var resp = await http.PostAsync("http://127.0.0.1:18000/v1/text/scan", content);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

Go

body := []byte(`{"text":"客户 john.doe@google.com，电话 +1-415-555-0142。","min_confidence":0.5}`)
resp, err := http.Post("http://127.0.0.1:18000/v1/text/scan",
    "application/json", bytes.NewReader(body))
// ...读取 resp.Body

值级批量（/v1/values/scan）

import requests

resp = requests.post(
    "http://127.0.0.1:18000/v1/values/scan",
    json={"values": [
        {"value": "john.doe@google.com", "label_hint": "email"},
        {"value": "123-45-6789",          "label_hint": "ssn"},
    ]},
    timeout=30,
)
for r in resp.json()["results"]:
    print(r["value_id"], r["pii_type"], r["confidence"], r["method"], r["role"])

附带判定证据（return_evidence=true）

curl -X POST http://127.0.0.1:18000/v1/values/scan \
  -H 'Content-Type: application/json' \
  -d '{"values":[{"value":"4111 1111 1111 1111","label_hint":"credit_card"}],"return_evidence":true}'

6. 集成最佳实践

1. 启动依赖检查：调用前先探测 /v1/health，确认 ready:true 再发请求，规避冷启动期 503。
2. 超时设置：单次 /v1/text/scan 客户端超时建议 ≥ 30 秒（首条请求含模型预热）；稳态下单篇通常为毫秒级。
3. 大批量文本：HTTP 单次一篇；海量文档建议在调用方并发（服务端并发上限由硬件档位决定，见 05-性能与容量）；超大批量结构化数据用值级 /v1/values/scan（分批调用，每批 ≤1000 条）。
4. 处理 needs_review：按业务制定策略——风控 / 合规场景建议人工或二次规则复核；一般场景可直接采信其类型标注。
5. 善用判定溯源：method 可用于统计判定路径分布与边界案例占比；需要完整判据时开启 return_evidence，用于审计取证与策略调优。
6. 幂等性：同一输入恒得同一结果，可放心重试、缓存、构建对比基线。
7. 坐标信息用途：start/end 可直接用于前端高亮、脱敏打码（如将 [start,end) 区间替换为 ***）。

04PII 类型清单

DataBrain 共支持 32 类敏感数据，按敏感度与判定可靠性分为四个类别。系统输出的 pii_type 字段即取自下表"类型"列。

类别说明

I-A · 强标识符（4 类，含数学校验）

I-B · 标识符（16 类，含格式/校验）

II-A · 常见 PII（9 类，上下文相关）

II-B · 本体属性（3 类，AI 语义识别）

覆盖广度

• 语种：AI 识别模型基于多语种预训练，覆盖 100+ 种语言（中、英、日、韩、印地语、欧洲多语等）。
• 地域：身份证覆盖 30+ 国格式、税号覆盖 20+ 国格式（依据内置类型定义），含中国大陆身份证 / 车牌 / 回乡证 / 证券账户、印度 Aadhaar/PAN/UPI/IFSC、日本 My Number、欧美各国 ID 等。
• 合规对标：上述类型覆盖主流数据保护法规所规管的敏感数据范畴（详见宣传彩页"合规对标"）。

05性能与容量

本章给出实测性能参考与硬件选型建议，供评估吞吐与容量。

1. 延时与吞吐（参考）

文档级（HTTP /v1/text/scan，单篇文本）

值级（批量分类基准）

2. 并发与吞吐说明

• 各硬件档的并发上限：CPU 档 4 / GPU-小档 8 / GPU-大档 16；
• 多请求可并发重叠，有效吞吐随并发提升，直至 GPU 算力饱和；
• 建议调用方按硬件档位的并发上限进行客户端并发控制，避免过载排队。

3. 选型建议

4. 容量估算示例

以 GPU-大档、文档级单流 ~100 篇/秒估算：

5. 显存与内存占用

• AI 模型：约 0.7 GB（多语种敏感数据识别模型，随镜像加密交付，启动时加载到显存）；
• 依赖层：约 2.7 GB（AI 运行时栈，磁盘占用，非常驻显存）；
• 运行峰值：建议显存 ≥ 8 GB、系统内存 ≥ 16 GB；
• 磁盘：镜像 ~3.4 GB，建议预留 ≥ 15 GB（含 2 版本回滚余量）；检测日志按日轮转、默认保留 180 天，并由磁盘水位保护兜底（剩余 < 2 GB 自动停写，见 06-安全与隐私）。

06安全与隐私

本章说明 DataBrain 在部署形态、数据处理、供应链与离线授权等方面的安全设计。

1. 数据不出网（离线部署）

• 完全离线运行：镜像通过离线包加载，运行时不连接 Docker Hub、不连接任何外部源、不发起任何外网请求。
• 数据不出客户网络：所有敏感数据的扫描与判定全部在客户自己的服务器/容器内完成，处理结果也只返回给调用方。
• 无遥测、无回传：系统不采集、不上报任何被扫描的内容或统计信息到奇点律动或第三方。

2. 数据持久化姿态

• 扫描默认实时计算：输入文本在内存中完成识别后即输出结果，不在磁盘持久化被扫描内容原文；运行日志（启动、健康、错误）不记录 PII。
• 检测日志（默认开启）：判定流水落盘供控制台审计页查阅与人工标注；记录中的值默认脱敏（仅保留首尾少量字符），按日轮转、默认保留 180 天，到期自动清理。
• 磁盘空间保护：磁盘剩余空间低于 2 GB 时自动暂停检测日志写入（优先保分类服务存活），恢复到约 3 GB 后自动续写；停写状态经 /v1/health 与控制台告警露出。
• 数据回流例外（默认开启，见 §9）：当请求携带合法 consent 时，系统会在客户本机磁盘加密留存一份被采样的 PII（用于人工复核 + 离线模型重训，AES-256-GCM 加密），受双闸门 + 留存期约束。

3. 容器安全

• 非 root 运行：容器以专用低权限用户 databrain 启动，不使用 root；
• 依赖隔离：容器自带全部运行时依赖（AI 推理框架、GPU 运行时等），与宿主机原生环境隔离，互不影响；
• 唯一共享资源：GPU 模式下，宿主机与容器仅共享显卡驱动（内核模块），不共享其他系统组件。

4. 数据控制权

控制台 Playground 捕获说明：操作员在控制台送检的文本默认进入自学习捕获管道（console-playground 客户桶，加密留存），用于审计页人工标注纠错。逐次退出：送检时勾选"不记录"（请求体 no_audit: true）则本次不捕获；整通道关闭：部署环境变量 DATABRAIN_CONSOLE_CONSENT=false（默认 true）。该桶的留存期清理与导出为显式运维操作（GET /v1/learning/export-corpus?customer=console-playground），不出现在控制台语料包默认视图。

5. 输入限制（防滥用）

• /v1/text/scan 单篇文本上限 100,000 字符（超出返回 422），防止超大 payload 滥用内存；
• min_confidence 由调用方控制发射阈值，可按场景在"高精度"与"高召回"间调节。

6. 合规姿态说明

DataBrain 的检测能力覆盖主流数据保护法规（GDPR、CCPA、中国 PIPL、HIPAA、PCI-DSS、SOC 2 等）所规管的敏感数据类型，并已建立类型级映射关系。

7. 升级与供应链安全

• 升级包（.sp）为离线增量包，加载前经 ECDSA 签名验签 + payload SHA-256 完整性比对（签名与负载哈希绑定，防"保签名换内容"）；控制台版本管理页上传的升级包执行同一校验链；
• 升级脚本内置路径穿越/绝对路径防御与版本格式校验，拒绝被篡改的包；
• 版本始终显式固定 tag（不用 :latest），便于审计与回滚。

8. 离线 License 授权

DataBrain 采用完全离线的授权：授权校验全部在客户侧本地完成，不发起任何外网请求、不回连奇点律动、无在线证明，可部署于严格气隔（air-gapped）环境。

• 本机绑定：License 与本机绑定，绑机器不绑容器——同一台机器上的容器重建不影响授权；每个部署实例需各自激活一份 License。更换主机或迁移到其他机器时需重新激活（详见 02“License（离线授权）”）。
• 闸门范围：/v1/text/scan、/v1/values/scan 需有效 License；/v1/health、/v1/license/status 始终开放用于诊断。
• 有效期与宽限：License 有到期日，到期后有宽限期（按授权类型），宽限满后扫描接口返回 403、健康/状态接口仍开放；到期前续期即可，无需重装。

激活流程见 02“License（离线授权）”；授权状态与续期见 07-运维与故障排查。

9. 数据回流（Data Reflow / 自学习数据采集）

数据回流让 DataBrain 越用越准：自动采样生产中「待复核」的判定样本 → 人工标注 → 导出加密语料包 → 交接离线模型重训。被采数据全程加密留存于客户本机，不出网。

不开启：无需任何改动

不携带下述请求头时，扫描 API 行为与平时完全一致，零采集。采集受双闸门 fail-closed 保护（部署时自动生成的加密密钥 + 逐请求 consent 头），任一缺失即完全不采集——能力预装，仅由请求头逐次激活。

开启采集：扫描请求加一个头

X-DataBrain-Consent: {"ts":"<YYYY-MM-DD>","crown_pii":true}

• 该头只影响本机内的采样与检测日志，不改变判定结果
• crown_pii: true 即同意该请求的 PII 原值入采集；省略该头 = 该次请求不采集

复核标注与语料管理由运营人员在控制台 /self-learning 及复核界面完成，无需调用方参与；数据主体行使删除权时联系运营处理。

07运维与故障排查

一键自检（在线诊断，首选）

控制台的故障诊断页（主机端口 18001 → 故障诊断）提供一键自检：对部署、启动、运行全流程执行 9 项检查点（6 组），每项一个信号灯 —— 🟢 绿=正常 / 🟡 黄=有异常但不影响核心功能 / 🔴 红=影响核心功能运行 / ⚪ 灰=不适用（如推理服务不可达时无法判定的依赖项）。

• 自动触发：系统启动后（首次安装 / 升级 / 主动重启）自动执行一次；模型加载期间会自动重试直至收敛出有意义的结果。
• 手动触发：点击「自检」按钮随时执行。
• 检查分组：服务运行（推理服务/运维代理）→ 授权（许可证，含临期/宽限期/待激活区分）→ 模型资产（识别模型组件完整性）→ 核心功能（内置样例检出验证，与发布前验证口径一致）→ 管道健康（审计落盘/审计索引）→ 数据落盘（存储写入）。内存/磁盘/GPU 等资源容量与质量门、漂移、p95 延迟等指标请查看仪表盘与健康告警页。
• 处置指引：每个黄/红灯附「处理建议」与跳转入口（如许可证激活、审计页、系统管理重启）；可展开查看原始数据。
• 主动告警：自检总评为红/黄时，控制台顶部告警栏会出现「自检发现异常」，并可经 webhook 外发（如已配置 DATABRAIN_ALERT_WEBHOOK_URL）。
• 结果留存：output/selfcheck/（含历史），随诊断包一起导出；首次安装未激活许可证时，自检显示黄灯「待激活」属预期状态。

故障打包（离线兜底）

当容器或控制台无法启动、需要把诊断信息发给支持团队时，在主机的安装目录直接跑：

bash databrain-ops.sh diagnose

• 产物：<安装目录>/diagnostics/diag_<时间戳>.zip（发给厂商）。
• 采集：版本 / 机器码 / health / license 状态 / 容器进程日志（docker compose logs）/ docker info / nvidia-smi，全部 best-effort——即使容器没起、没有 docker，也会产出可用的部分诊断包。
• 脱敏：自动剔除敏感环境变量值；License 文件与各类密钥材料绝不打包。
• 容器正常运行时，更推荐用控制台的故障排查页（主机端口 18001）一键打包，内容更全（含审计样本 / 指标时序 / 模型版本），同样脱敏。

1. 日常运维命令

以下及本章后文的 databrain-ops.sh 命令，均在安装目录执行（或先将安装目录加入 PATH，见下方提示）。

2. 监控要点

3. 版本管理

• 始终显式固定 TAG（如 TAG=1.0.1），不要使用 :latest，便于审计与精确回滚；
• 建议保留最近 2 个应用版本（当前 + 上一版），以便瞬时回滚；
• 依赖层（base）不要手动删除——它体积大但变化稀疏（约每年一次），且是回滚关键；无任何应用版本引用的"孤儿"依赖层再手动清理；
• 升级由应用 siipulse 包（bash siipulse-rel_databrain_<新版本>.sp）自动处理"验签 → 加载 → 健康门禁 → 失败回滚"全流程，复用本机已装的 BaseImage；控制台版本管理页上传的 .sp 包执行同一签名与完整性校验（见 06-安全与隐私 §7）。

4. 回滚 / 撤销 / 清理 / 依赖自检

4.1 回滚到指定版本 rollback

# 切回任意一个仍在本机镜像仓的旧版本（依赖层与旧应用镜像仍在）
bash databrain-ops.sh rollback <旧版本号>

回滚是秒级操作（仅切换 tag + 重启 + 模型重载 ~30–70 秒）。

4.2 撤销最近一次升级 revert

# 不必记版本号：回到升级前的版本（安装器自动记录）
bash databrain-ops.sh revert

revert 与 rollback 的区别：rollback <ver> 需显式指定版本号，可切到任意旧版；revert 无参数，专门“撤销上一次升级”，依赖安装器记录的上一版本号。两者都不触动 License 卷。

4.3 从零清理 clear（危险）

极端排障或换机前，可彻底清理本次安装物、回到“只剩交付包”的状态：

bash databrain-ops.sh clear        # 交互确认（输入 YES）
bash databrain-ops.sh clear --yes  # 跳过确认（脚本/自动化用）

clear 会：停删容器 → 删除所有 siipulse-databrain:* 应用镜像 → 删除 compose 与安装状态文件。保留：license/（授权卷，免再激活）、*.sp 交付包、siipulse-baseimage:1.0（基座，免重 load）。清理后用 bash siipulse-rel_databrain_<版本号>.sp 即可重装。

4.4 依赖自检 deps

确认当前基座镜像是否包含全部运行时依赖（依赖清单见交付包内 requirements.lock）：

bash databrain-ops.sh deps

在基座镜像内逐项核对 torch / transformers / fastapi 等关键组件的已装版本，缺失项标记为 MISS。用于交付验收或排障时回答“基座是否完整”。

5. 故障排查表

License 续期

License 到期前应续期，避免扫描中断：

1. 主机硬件未变 → 可直接复用原机器码，向签发方换取新 license.json；
2. 主机硬件已变更 → 重新采集机器码 bash databrain-ops.sh fingerprint，再换取；
3. 装入新 License 并重启生效：bash databrain-ops.sh activate license.json（= 替换 license/license.json + restart + 校验）；
4. 过期后进入宽限期（按授权类型），宽限满扫描 403；续期后立即恢复，无需重装镜像。

6. 日志解读

启动日志会依次出现以下关键信号（具体格式以实际输出为准）：

• 硬件探测完成，确定生效档位（如 profile=gpu-large，对应"GPU-大档"）；
• 引擎加载就绪，给出该档位的并发上限；
• HTTP 服务开始监听端口（容器内 8000，主机发布 18000）。

7. 在 Kubernetes 等编排平台部署

交付默认以 Docker Compose 形式提供。若需在 Kubernetes 等平台部署：

• 将镜像导入镜像仓（docker load 后 docker tag + push，或直接用离线包）；
• 以 Deployment 运行单副本（或按需多副本水平扩展）；
• 配置就绪/存活探针指向 GET /v1/health，就绪条件为 ready:true；
• GPU 模式按平台方式声明 GPU 资源（如 K8s 的 nvidia.com/gpu）。

8. 获取支持

排查时建议准备以下信息，便于快速定位：

1. DataBrain 版本号（docker images siipulse-databrain 的 TAG，或 bash databrain-ops.sh version）；
2. 启动日志全文（docker compose logs databrain）；
3. 硬件配置（CPU/内存/GPU 型号与显存、操作系统）；
4. 复现步骤与请求/响应（请脱敏后再发送，勿发送真实 PII）。

08常见问题（FAQ）