重要提示。 仅扫描你拥有或已获得书面授权的网络。UltraViolet 执行被动服务侦察——它不会利用漏洞。

为什么选择 UltraViolet

单租户、一套 Docker Compose 栈、完全掌控你的数据。

✨ 功能特性

发现

• 以 masscan 或 zmap 作为发现引擎的 TCP connect 扫描器
• 可配置端口上的 UDP 探测
• 通过 SCAN_ALLOWED_CIDRS 限定范围，并带有主机与端口限制

深度探测（约 100 种协议）

• Web：HTTP/HTTPS、HTTP/3、GraphQL、favicon 哈希、robots.txt、security.txt、技术栈
• TLS：证书链、JARM、JA3S/JA4S、配置评级
• 邮件与目录服务：SMTP、POP3/IMAP、LDAP、IPMI
• 数据库与消息队列：MySQL、PostgreSQL、MongoDB、Redis、Kafka、MQTT、NATS、AMQP…
• ICS/SCADA：Modbus、BACnet、DNP3、IEC 104、S7Comm、ENIP、OPC UA…
• IoT 与媒体：ONVIF、RTSP、Chromecast、AirPlay、UPnP…
• 完整列表见协议文档

数据丰富

• 反向 DNS、GeoIP（MMDB）、ASN
• 可选的正向 DNS 与 CT 日志发现

CVE 与风险

• 本地 NVD 镜像，支持后台同步与基于指纹的匹配
• CISA KEV 与 FIRST EPSS

运维

• RBAC（viewer / operator / admin）、JWT + 刷新令牌
• 扫描计划、暂停/恢复、工作进程重启后的孤儿任务回收
• Prometheus /metrics、可选的 Grafana 配置
• 审计日志、速率限制、保留策略

🏗 架构

flowchart TB
  Browser["Browser"]
  FE["service-frontend<br/>React + nginx"]
  API["uv-api<br/>REST · WS · metrics"]
  PG[("PostgreSQL 16")]
  SCAN["uv-scanner<br/>probe pipeline"]

  Browser --> FE
  FE -->|"/api"| API
  FE -->|"/realtime"| API
  API <--> PG
  SCAN <--> PG
  API -.->|LISTEN/NOTIFY| API

发布版 UI 镜像将 /api/ 和 /realtime 代理到 uv-api——单一来源，无需针对每个 API URL 重新构建前端。

后端开发规则：CLAUDE.md。

🚀 快速开始

环境要求： Go 1.25+、Docker Engine ≥ 24、约 4 GB 内存。生产镜像面向 Linux amd64。

从 Docker Hub 运行（无需源码构建）

新手路径——使用 service-env/docker-compose.registry.yml 拉取已发布镜像：

cd service-env
cp env.registry.example .env
# 设置 POSTGRES_PASSWORD、AUTH_JWT_SECRET、AUTH_BOOTSTRAP_PASSWORD
mkdir -p geoip catalog-seed
docker compose -f docker-compose.registry.yml pull
docker compose -f docker-compose.registry.yml up -d
# UI → http://localhost:3000

参见文档站点中的 Docker Registry。

从源码开发

API/扫描器镜像会复制 service-api/bin/ 中预构建的二进制文件（它们不会在 Docker 内部编译）。make dev 会在 docker compose … --build 之前运行 make -C service-api build-linux。

git clone https://github.com/yakushstanislav/UltraViolet.git
cd UltraViolet/service-env

cp .env.example .env
mkdir -p secrets
openssl rand -hex 32 > secrets/postgres_password
openssl rand -hex 32 > secrets/auth_jwt_secret

cd ..
make dev

开发引导账号： admin / admin（仅在 APP_ENV≠production 时有效）。

📖 文档

完整指南——VitePress 位于 service-documentation-frontend/docs/：

make docs-dev    # → http://localhost:5173

在生产环境中，启用 docs 配置：

cd service-env && docker compose --profile docs up -d
# → http://localhost:${UV_DOCUMENTATION_PORT:-3002}

关键章节：安装 · 扫描 · API · 部署 · 离线安装。

🛠 开发

完整 Docker

make dev    # build-linux → compose prod + dev override --build

后端代码变更后重新构建 Go 二进制文件（make -C service-api build-linux），然后重启或重新运行 make dev。

混合模式（更快的后端迭代）

make dev-db   # 仅在 :5432 上运行 PostgreSQL

cd service-api && make build
export LOGGER_NAME=uv-api LOGGER_DEBUG=true
export SERVER_ADDR=0.0.0.0 SERVER_PORT=8080
export METRICS_ADDR=0.0.0.0 METRICS_PORT=9090
export REALTIME_ADDR=0.0.0.0 REALTIME_PORT=8081
export POSTGRES_ADDR=localhost POSTGRES_PORT=5432
export POSTGRES_USERNAME=ultraviolet
export POSTGRES_PASSWORD="$(cat ../service-env/secrets/postgres_password)"
export POSTGRES_DATABASE=ultraviolet
export POSTGRES_SCHEMA_PATH="$(pwd)/deploy/migrations"
export AUTH_JWT_SECRET="$(cat ../service-env/secrets/auth_jwt_secret)"
./bin/uv-api

前端：cd service-frontend && npm run dev（Vite 将 /api 代理到 :8080，将 /realtime 代理到 :8081）。

GeoIP 与 CVE

cd service-env && make geoip-download      # IPLocate MMDB → geoip/
make -C service-env cve-catalog-dump       # CVE 数据导出（需要正在运行的 postgres）

不使用 Docker 构建

make build && make lint && make frontend-build && make docs-build

📦 发布与安装

目标平台： linux/amd64。在 Apple Silicon 上，为离线归档设置 DOCKER_PLATFORM=linux/amd64。

git tag v0.1.0
make release VERSION=v0.1.0
make release-promote VERSION=v0.1.0   # :latest——本地发布必需；GitHub Actions 会自动执行此操作

在线安装： 解压 → cp .env.example .env → ./install.sh（从 registry 拉取）。

离线安装： ./install.sh（docker load，不拉取）。升级：保留 .env、secrets/ 和 Postgres 卷 → ./upgrade.sh。

变量：UV_REGISTRY（默认 docker.io/styakush）、DRY_RUN=1——本地冒烟构建，不推送。

# 在构建机器上
scp dist/ultraviolet-v0.1.0-offline.tar.gz user@host:~/

# 在服务器上（Docker ≥ 24，amd64）
tar xzf ultraviolet-v0.1.0-offline.tar.gz && cd ultraviolet-v0.1.0
cp .env.example .env
./install.sh

docker compose -f docker-compose.yml down
# 备份 .env + secrets/，解压新归档，运行 ./upgrade.sh

✅ 生产环境检查清单

1. 将密钥存储在 secrets/ 中，切勿提交到 git。
2. 将 CORS_ALLOWED_ORIGINS 仅设置为真实的 UI 来源。
3. 配置 SCAN_ALLOWED_CIDRS 以及主机/端口限制。
4. 更改引导密码和 AUTH_JWT_SECRET（install.sh 会拒绝占位符）。
5. 设置 APP_ENV=production——uv-api 会拒绝 admin/admin 以及少于 8 个字符的密码。
6. 在反向代理处终止 TLS——示例：service-env/examples/nginx-tls.conf。
7. 位于代理之后时：设置 AUDIT_TRUST_PROXY_HEADERS=true。
8. 备份 PostgreSQL：service-env/scripts/backup.sh + cron；upgrade.sh 也会创建转储。
9. 指标位于 :9090/metrics；通过 配置使用 Grafana。

# docker-compose.override.yml
services:
  service-frontend:
    ports:
      - "127.0.0.1:3000:8080"

CORS_ALLOWED_ORIGINS=https://ultraviolet.example.com
AUDIT_TRUST_PROXY_HEADERS=true

VITE_BASE_PATH=/ultraviolet/ make frontend-build
# compose 中设置 UV_BASE_PATH=/ultraviolet/——必须与 VITE_BASE_PATH 一致

0 3 * * * cd /opt/ultraviolet/service-env && ./scripts/backup.sh && find backups -name 'uv-*.dump' -mtime +14 -delete

0 4 1 * * cd /opt/ultraviolet/service-env && ./scripts/geoip-refresh.sh >> /var/log/uv-geoip.log 2>&1

🔐 API 与 RBAC

执行 POST /v1/auth/login 后，你将获得一个 access_token（Bearer）和 refresh_token（/v1/auth/refresh）。

GET /v1/me · GET /v1/version · GET /readyz（健康检查 + 版本 + 提交）。

🤝 贡献

参见 CONTRIBUTING.md。安全报告：SECURITY.md。 社区规范：CODE_OF_CONDUCT.md。

📄 许可证

UltraViolet 以 MIT License 发布。

_{UltraViolet——发现你所拥有的，了解发生了什么变化，将其保留在你的网络中。}