bangwen/README.zh-CN.md

榜文 (bangwen) 🚀

基于 VictoriaMetrics 极简架构哲学构建的高性能公开招考数据聚合、混合检索与白盒简历匹配引擎。

---

📖 目录

• ✨ 核心特性
• 🏛️ 系统架构
• 🚀 快速开始
  • 环境准备
  • 安装与部署
  • 验证运行
• 🛠️ 使用指南
  • Web 控制台
  • CLI 命令行工具
  • HTTP API 接口参考
• ⚙️ 环境配置
• 🔒 安全加固说明
• 🤝 参与贡献
• 📜 开源协议
• 🤖 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 与 Docker Compose v2+
• 本地原生开发环境（可选）：
  • Rust (>= 1.80)
  • uv (>= 0.4.0) 与 Python 3.12+

安装与部署

1. 克隆代码仓库：

   git clone [email protected]:bitfennec/bangwen.git
   cd bangwen
   

2. 初始化环境与鉴权凭据：

   cp .env.example .env
   # 自动生成 64 位高强度随机鉴权 Token
   sed -i "s/replace_with_your_secure_secret_token/$(openssl rand -hex 32)/" .env
   

3. 使用 Docker Compose 一键构建启动：

   docker compose up -d --build
   

验证运行

检查服务运行状态与初始入库指标：

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 或原生编译二进制进行操作：

# 从文件或 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。提交改动前请确保通过本地基线检验：

# Rust 内核验证
cargo test --offline
cargo clippy --all-targets -- -D warnings

# 采集端回归验证
cd collectors && uv run python tests/test_content_and_security.py

---

📜 开源协议

本项目采用 MIT 开源协议。

---

🤖 AI Agent 集成

针对作为 Agent 工具调用的集成场景，请参阅 skill/SKILL.md，了解调用协议、结构化输出规范以及不可信数据的安全隔离要求。

(回到顶部)