bitfennec
5a8af5729c
- Add English README.md and Chinese README.zh-CN.md for project root - Enhance collectors/README.md and add Chinese collectors/README.zh-CN.md - Document architecture, deployment, security invariants, and CLI/API usage
226 lines
10 KiB
Markdown
226 lines
10 KiB
Markdown
<a id="readme-top"></a>
|
||
|
||
# 榜文 (bangwen) 🚀
|
||
|
||
> **基于 VictoriaMetrics 极简架构哲学构建的高性能公开招考数据聚合、混合检索与白盒简历匹配引擎。**
|
||
|
||
---
|
||
|
||
## 📖 目录
|
||
- [✨ 核心特性](#-核心特性)
|
||
- [🏛️ 系统架构](#️-系统架构)
|
||
- [🚀 快速开始](#-快速开始)
|
||
- [环境准备](#环境准备)
|
||
- [安装与部署](#安装与部署)
|
||
- [验证运行](#验证运行)
|
||
- [🛠️ 使用指南](#️-使用指南)
|
||
- [Web 控制台](#web-控制台)
|
||
- [CLI 命令行工具](#cli-命令行工具)
|
||
- [HTTP API 接口参考](#http-api-接口参考)
|
||
- [⚙️ 环境配置](#️-环境配置)
|
||
- [🔒 安全加固说明](#-安全加固说明)
|
||
- [🤝 参与贡献](#-参与贡献)
|
||
- [📜 开源协议](#-开源协议)
|
||
- [🤖 AI Agent 集成](#-ai-agent-集成)
|
||
|
||
---
|
||
|
||
## ✨ 核心特性
|
||
|
||
- **⚡ 对标 VictoriaMetrics 架构哲学**：单微核 Rust 二进制文件同时承载 HTTP 摄入网关、混合检索核心与内嵌 Web 控制台，杜绝过度微服务化与复杂外部依赖。
|
||
- **🛡️ 多级排重与数据治理管线**：融合规范化 URL 权威归一、16 字符内容哈希校验、64 位汉明距离 SimHash 以及针对短文本（<200 字符）的防误杀二次核验机制。
|
||
- **🎯 客观透明的白盒简历匹配**：基于法定与招聘硬性门槛（GB/T 2260 行政区划字典、标准学历档次映射、年龄区间与专业/技能对齐）进行确定性白盒匹配，直接输出透明合规与不符事实清单。
|
||
- **🔍 多路混合检索与 RRF 融合**：深度集成 SQL 精确过滤、PostgreSQL `pg_trgm` GIN 模糊索引以及 `pgvector` HNSW 向量余弦距离检索，通过 RRF（Reciprocal Rank Fusion）算法兼顾高召回与高精度。
|
||
- **🕸️ 边缘采集双模调度引擎**：Python 边缘爬虫体系，同时支持轻量级声明式 TOML 配置卡片与复杂场景定制 Python 适配器，按域名分组并发调度并执行站内串行礼貌降频。
|
||
- **🔒 全面收敛的安全防护基线**：
|
||
- 严格的内容安全策略（CSP `script-src 'self'`，彻底移除 `'unsafe-inline'`）。
|
||
- 终端控制序列无死角清洗（剥离 ANSI CSI、OSC 52 剪贴板指令与控制字符）。
|
||
- Markdown URL 注入拦截与爬虫逐跳重定向 SSRF 白名单校验。
|
||
- 容器服务全量以非 root 专属系统用户（`UID 10001`）隔离执行。
|
||
|
||
---
|
||
|
||
## 🏛️ 系统架构
|
||
|
||
```
|
||
+---------------------------------------+
|
||
| 各省市公开招考招聘政务网 |
|
||
+---------------------------------------+
|
||
|
|
||
(HTTP 抓取与域名礼貌限速调度)
|
||
v
|
||
+---------------------------------------+
|
||
| bangwen-collector (Python) |
|
||
| - 声明式 TOML 站点卡片 (sources/) |
|
||
| - 定制化抓取适配器 (adapters/) |
|
||
| - SSRF 防护型 PoliteFetcher 客户端 |
|
||
+---------------------------------------+
|
||
|
|
||
(HTTP POST /api/v1/ingest)
|
||
Bearer Token 鉴权通信
|
||
v
|
||
+---------------------------------------+
|
||
| bangwen-core (Rust) |
|
||
| - SimHash & 内容哈希多级排重管线 |
|
||
| - 多路混合检索与白盒简历打分内核 |
|
||
| - 纯原生内嵌 Web 控制台与静态资源 |
|
||
+---------------------------------------+
|
||
|
|
||
(SQL 与向量存储)
|
||
v
|
||
+---------------------------------------+
|
||
| PostgreSQL 16 + pgvector |
|
||
| - announcement 与 position 数据基表 |
|
||
| - pg_trgm 倒排与 HNSW 向量近似索引 |
|
||
+---------------------------------------+
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境准备
|
||
- [Docker](https://docs.docker.com/engine/install/) 与 [Docker Compose](https://docs.docker.com/compose/) v2+
|
||
- 本地原生开发环境（可选）：
|
||
- [Rust](https://rustup.rs/) (>= 1.80)
|
||
- [uv](https://docs.astral.sh/uv/) (>= 0.4.0) 与 Python 3.12+
|
||
|
||
### 安装与部署
|
||
|
||
1. **克隆代码仓库**：
|
||
```bash
|
||
git clone [email protected]:bitfennec/bangwen.git
|
||
cd bangwen
|
||
```
|
||
|
||
2. **初始化环境与鉴权凭据**：
|
||
```bash
|
||
cp .env.example .env
|
||
# 自动生成 64 位高强度随机鉴权 Token
|
||
sed -i "s/replace_with_your_secure_secret_token/$(openssl rand -hex 32)/" .env
|
||
```
|
||
|
||
3. **使用 Docker Compose 一键构建启动**：
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 验证运行
|
||
|
||
检查服务运行状态与初始入库指标：
|
||
```bash
|
||
curl -s http://127.0.0.1:8080/health
|
||
# 预期输出: {"status":"ok"}
|
||
|
||
curl -s http://127.0.0.1:8080/api/v1/stats
|
||
# 预期输出: {"announcements":...,"embeddings":0,"positions":...,"sources":6,"status":"ok","vector_ready":false}
|
||
```
|
||
|
||
在浏览器中打开 `http://127.0.0.1:8080/` 即可直接进入内嵌 Web 控制台。
|
||
|
||
---
|
||
|
||
## 🛠️ 使用指南
|
||
|
||
### Web 控制台
|
||
服务启动后直接监听 `http://127.0.0.1:8080/`：
|
||
- **公告 Feed 流**：按时间倒序分页展示各省市招考公告，支持全文实时一键折叠/展开、挂载结构化职位列表与官方附件直接下载。
|
||
- **多维综合检索**：支持按关键词、标准行政区划编码、编制用人性质及最低学历门槛组合筛选。
|
||
- **白盒简历匹配**：输入候选人基础画像，系统秒级匹配合规在招岗位，透明标明硬性满足与不符条款。
|
||
- **每日聚合日报**：一键生成与复制过去 24 小时收录的招考精选与即将截止报名清单（Markdown 格式）。
|
||
- **采集节点监控**：实时查看各边缘节点的连通健康度、认证态与最近上报统计。
|
||
|
||
### CLI 命令行工具
|
||
|
||
通过宿主机自带的原生穿透脚本 `./bin/bangwen` 或原生编译二进制进行操作：
|
||
|
||
```bash
|
||
# 从文件或 stdin 管道摄入数据
|
||
./bin/bangwen ingest --file ./sample.json
|
||
|
||
# 多维检索符合条件的岗位 (例如玉溪 530400)
|
||
./bin/bangwen search "运维" --region 530400 --json
|
||
|
||
# 查看公告或具体岗位详情
|
||
./bin/bangwen show ann:1 --json
|
||
./bin/bangwen show pos:3 --json
|
||
|
||
# 根据候选人画像执行白盒打分匹配
|
||
./bin/bangwen match --resume ./tests/fixtures/sample_resume.json --top 10
|
||
|
||
# 输出今日招考聚合日报
|
||
./bin/bangwen digest
|
||
|
||
# 检查各边缘采集源的健康状态
|
||
./bin/bangwen sources
|
||
```
|
||
|
||
### HTTP API 接口参考
|
||
|
||
| 端点路由 | 请求方式 | 功能简述 | 鉴权要求 |
|
||
|----------|----------|----------|----------|
|
||
| `/health` | `GET` | 核心服务与数据库连通性健康检查 | 无 |
|
||
| `/api/v1/ingest` | `POST` | 批量数据推送摄入接口 | Bearer Token |
|
||
| `/api/v1/stats` | `GET` | 系统汇总指标与向量就绪状态 | 无 |
|
||
| `/api/v1/sources` | `GET` | 采集节点健康度与最近入库明细 | 无 |
|
||
| `/api/v1/announcements` | `GET` | 公告分页列表（支持关键字与类型筛选） | 无 |
|
||
| `/api/v1/announcements/{id}` | `GET` | 单篇公告详情（含下属岗位与附件） | 无 |
|
||
| `/api/v1/positions/{id}` | `GET` | 细分结构化招考岗位详情 | 无 |
|
||
| `/api/v1/search` | `GET` | 混合关键字多路检索接口 | 无 |
|
||
| `/api/v1/match` | `POST` | 候选人简历白盒打分与核验接口 | 无 |
|
||
| `/api/v1/digest` | `GET` | 今日招考聚合日报（Markdown 格式） | 无 |
|
||
|
||
---
|
||
|
||
## ⚙️ 环境配置
|
||
|
||
在 `.env` 中配置的环境变量说明：
|
||
|
||
| 变量名 | 默认值 | 是否必填 | 说明 |
|
||
|--------|--------|----------|------|
|
||
| `DATABASE_URL` | `postgres://bangwen:bangwen_dev@postgres:5432/bangwen` | 是 | PostgreSQL + pgvector 数据库连接串 |
|
||
| `INGEST_TOKEN` | *空* | 推荐 | 用于保护 `/api/v1/ingest` 端点的 Bearer 鉴权密钥 |
|
||
| `SERVER_HOST` | `0.0.0.0` | 否 | Rust HTTP 服务监听地址 |
|
||
| `SERVER_PORT` | `8080` | 否 | Rust HTTP 服务监听端口 |
|
||
| `LOG_LEVEL` | `info` | 否 | 日志级别（`error`, `warn`, `info`, `debug`） |
|
||
| `OLLAMA_BASE_URL` | `http://host.docker.internal:11434` | 否 | 向量生成所用的 Ollama 服务地址 |
|
||
| `EMBEDDING_MODEL` | `bge-m3` | 否 | Ollama 向量模型名称 |
|
||
|
||
---
|
||
|
||
## 🔒 安全加固说明
|
||
|
||
- **非 Root 容器降权**：`bangwen-core` 与 `bangwen-collector` 容器镜像均配置专用非特权运行用户（`UID 10001`）。
|
||
- **严格 CSP 策略**：响应头强制 `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';`，彻底根除内联脚本注入执行风险。
|
||
- **接口算力与内存保护**：对简历匹配接口增加完备的参数边界防护（技能最大 50 项、城市最大 20 项、学历上限 32 字符、出生年份 1940~当年区间强校验），深度分页 offset 上限 10000 强校验拦截。
|
||
- **并发摄入防死锁**：数据落库事务内强制按照规范化 URL 字典序申请行级排他锁，彻底根除 PostgreSQL `40P01` 死锁异常。
|
||
- **SSRF 与重定向逐跳校验**：HTTP 抓取客户端内置私有内网 IP 过滤、严格域名白名单与逐跳重定向安全性验证。
|
||
|
||
---
|
||
|
||
## 🤝 参与贡献
|
||
|
||
欢迎提交 Issue 与 Pull Request。提交改动前请确保通过本地基线检验：
|
||
```bash
|
||
# Rust 内核验证
|
||
cargo test --offline
|
||
cargo clippy --all-targets -- -D warnings
|
||
|
||
# 采集端回归验证
|
||
cd collectors && uv run python tests/test_content_and_security.py
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 开源协议
|
||
|
||
本项目采用 [MIT](LICENSE) 开源协议。
|
||
|
||
---
|
||
|
||
## 🤖 AI Agent 集成
|
||
|
||
针对作为 Agent 工具调用的集成场景，请参阅 [`skill/SKILL.md`](./skill/SKILL.md)，了解调用协议、结构化输出规范以及不可信数据的安全隔离要求。
|
||
|
||
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
|