# DBVigil 社区预览版使用手册

版本：0.2.0-preview.1  
平台：Anolis OS 8.x/23.x，x86_64/aarch64
发布日期：2026-09-08

## 1. 产品定位

DBVigil 通过被动抓取数据库网络流量，关联会话、SQL、响应状态、影响行数、
结果集及 SQL 语义信息，并提供资产、策略、告警、会话轨迹和证据详情页面。
社区预览版适合功能体验、协议兼容验证和小规模试点，不代表合规认证或商用 SLA。

当前主要试用 MySQL 和 PostgreSQL 明文协议；Oracle、达梦为协议预览。
TLS 加密报文在未提供会话密钥时只能识别连接，不能解码 SQL 和结果内容。
MSSQL 不在本版本的公开支持范围内。

## 2. 部署前准备

### 2.1 服务器

- Anolis OS 大版本和 CPU 架构必须与安装包文件名一致。
- 最低 2 核 CPU、4 GB 内存、40 GB 可用磁盘。
- 建议 4 核 CPU、8 GB 内存、100 GB 以上独立数据盘。
- 安装需要 root 权限；默认 Web 端口为 8080。

### 2.2 流量接入

推荐将数据库服务器所在交换机端口的双向流量镜像到 DBVigil 采集网卡。
必须同时看到客户端到数据库和数据库到客户端两个方向。云环境可使用虚拟网络
流量镜像；审计本机连接时，应选择实际承载流量的网卡或回环网卡。

在安装前确认网卡：

```bash
ip -br link
ip route show default
sudo tcpdump -ni eth0 'tcp port 3306 or tcp port 5432 or tcp port 1521 or tcp port 5236' -c 10
```

如果 `tcpdump` 看不到双向数据库流量，DBVigil 也无法完成协议解码。

## 3. 安装

把安装包和 `.sha256` 文件放在同一目录：

```bash
sha256sum -c dbvigil-0.2.0-preview.1-anolis8-x86_64.tar.gz.sha256
tar -xzf dbvigil-0.2.0-preview.1-anolis8-x86_64.tar.gz
cd dbvigil-0.2.0-preview.1-anolis8-x86_64
sudo ./install.sh --offline
```

安装器默认使用默认路由网卡。镜像流量位于其他网卡时再增加 `--interface ens192`。
离线包携带所需 RPM 和 Python wheels；
安装器会创建 PostgreSQL 数据库、运行迁移、注册 systemd 服务，并自动生成
数据库密码和初始管理员密码。

自定义强密码时，密码长度为 12 至 128 字符：

```bash
sudo ./install.sh --offline --interface ens192 \
  --db-password 'Change-Database-Password' \
  --admin-password 'Change-Admin-Password'
```

凭据保存在 `/etc/dbvigil/dbvigil.env`，权限为 `0640`。不要将该文件发送给
他人或提交到代码仓库。

## 4. 首次使用

浏览器访问 `http://服务器IP:8080/`，使用安装器输出的 `admin` 密码登录。
进入“系统设置”，修改当前密码。随后依次检查：

1. “资产管理”是否识别数据库地址、端口和类型。
2. “会话审计”是否出现客户端、数据库、账号和连接时间。
3. “SQL 审计”是否显示 SQL、操作类型、响应状态和影响行数。
4. SQL 详情中的结果列名、返回行及语义对象是否符合实际执行结果。
5. “告警调查”能否从告警回溯到会话、SQL 和证据详情。

抓包完成后，文件会由定时任务导入，语义解析和告警处理是异步的，页面通常会有
几十秒延迟。

## 5. 配置

主要配置文件：

- `/etc/dbvigil/dbvigil.env`：数据库、Web、目录和容量参数。
- `/etc/dbvigil/decoder.conf`：采集网卡、BPF 过滤条件和解码输出。

修改采集网卡或端口后重启采集服务：

```bash
sudo systemctl restart dbvigil-capture
sudo journalctl -u dbvigil-capture -n 50 --no-pager
```

默认监听 MySQL 3306/3506、PostgreSQL 5432、Oracle 1521/1522、达梦 5236。
只保留实际使用的端口可以降低采集开销。

## 6. 服务与目录

```bash
sudo dbvigil-healthcheck
sudo systemctl status dbvigil-capture dbvigil-web \
  dbvigil-semantic-worker dbvigil-alert-worker --no-pager
sudo systemctl list-timers 'dbvigil-*'
```

- 程序：`/opt/dbvigil/current`
- 配置：`/etc/dbvigil`
- 解码输出与归档：`/var/lib/dbvigil`
- PostgreSQL：`/var/lib/pgsql/data`
- 日志：`/var/log/dbvigil`

容量清理服务默认安装但不启用，避免未确认策略时自动删除审计记录。确认至少保留
天数及合规要求后再启用：

```bash
sudo systemctl enable --now dbvigil-storage-pressure.timer
```

其默认策略是在磁盘使用率达到 85% 时清理最旧完整日期，停止于 80%，至少保留
最近 7 天，每次最多处理 3 天。正式环境应先修改
`DBVIGIL_STORAGE_MIN_RETAIN_DAYS`，并备份后再启用。

## 7. 安全建议

- 仅向管理网开放 8080，禁止直接暴露到公网。
- 正式试点应通过 Nginx 等反向代理启用 HTTPS。
- 首次登录立即修改管理员密码，并为每位用户创建独立账号。
- 结果集可能包含敏感数据，应限制审计员权限并设置保留周期。
- 定期备份 PostgreSQL、`/etc/dbvigil` 和证据密钥；备份应异机保存。
- 在获得网络和数据所有者授权后再采集数据库流量。

## 8. 验证与排障

### 页面没有数据

```bash
sudo tcpdump -ni eth0 'tcp port 3306 or tcp port 5432' -c 20
sudo journalctl -u dbvigil-capture -n 100 --no-pager
sudo journalctl -u dbvigil-import -n 100 --no-pager
ls -lh /var/lib/dbvigil/out
```

重点确认网卡、端口、双向镜像和 TLS 状态。容器、NAT 或代理场景下，页面地址
可能显示转换后的端点，应结合网络拓扑核对。

### 健康检查失败

```bash
sudo dbvigil-healthcheck
df -h /
df -i /
sudo systemctl --failed
```

当磁盘接近阈值时先停止压测，完成备份和容量扩展，不要直接删除 PostgreSQL
数据文件。

### 解码字段不完整

保存原始 PCAP、数据库类型及版本、客户端/驱动版本、实际 SQL 和期望结果，提交到
官网技术支持入口。不要上传包含真实密码或个人敏感信息的抓包。

## 9. 升级、备份与卸载

升级前执行数据库备份：

```bash
sudo -u postgres pg_dump -Fc dbvigil > dbvigil-backup.dump
sudo tar -czf dbvigil-config-backup.tar.gz /etc/dbvigil
```

解压新版后重新运行 `install.sh`。安装器会保留配置和数据库，安装新 release 并
切换 `/opt/dbvigil/current`。

仅卸载程序并保留数据：

```bash
sudo dbvigil-uninstall
```

永久删除程序、数据库、配置和全部审计数据：

```bash
sudo dbvigil-uninstall --purge
```

`--purge` 不可恢复，执行前必须备份。

## 10. 已知限制

- 安装包不能跨 Anolis 大版本或 CPU 架构使用。
- TLS 加密负载默认无法解码。
- 丢包、乱序、截断报文及客户端版本差异可能造成字段缺失。
- Oracle 和达梦仍处于兼容性扩展阶段，应使用业务样本验证。
- 当前为单机部署，不提供高可用、集中多节点管理或合规认证承诺。