从哪里开始
ocr-web 用于在网页上检查代码、管理规则和阅读扫描结果。日常使用从工作台开始;管理员需要提前准备模型连接和扫描工具。
| 你要做什么 | 入口与操作 |
|---|---|
| 第一次检查项目 | 工作台 → 添加项目 → 连接 GitLab 或上传 ZIP |
| 查看某个分支的问题 | 打开项目 → 选择分支 → 查看问题(进入对应报告) |
| 修复后重新检查 | 将修复提交到原分支 → 扫描最新代码 |
| 调整扫描参数 | 项目分支页 → 扫描最新代码 → 确认设置 |
| 选择参与扫描的已有条款 | 规则库 → 对应语言 → 调整开关并保存 |
| 阅读或保存完整结果 | 项目中的查看报告,或扫描报告 |
| 第一次安装或连接模型 | 本文的管理员准备 |
- 01导入代码选择 GitLab 分支或上传源码 ZIP
- 02执行扫描等待代码检查与报告生成
- 03查看问题核对版本、覆盖与问题详情
- 04修复复扫提交修改后扫描最新代码
- 05保存报告下载需要保留的结果
导入 GitLab 项目
- 在工作台点击「添加项目」,选择「连接 GitLab」。
- 搜索仓库名称,或粘贴仓库链接,选择需要检查的仓库。
- 选择分支。页面默认选择仓库的默认分支,也可以搜索其他分支。
- 点击「下一步:扫描设置」,选择范围与排除项,再点击「开始扫描」。系统固定代码提交并按设置准备待查文件。
- 进入项目页查看进度;完成后查看分支结果摘要,点击「查看问题」进入对应报告。
同一个仓库复用一个项目。检查其他分支时,在项目页点击「选择分支 / 上传代码」。各分支分别保存问题与扫描记录,查看结果时先核对分支名称和扫描版本。
首次使用:管理员配置团队 GitLab
在「添加项目 → 连接 GitLab」中点击「配置连接」,填写团队 GitLab 地址与访问令牌,然后点击「验证并保存」。团队账号需要具有目标仓库的读取权限,令牌需要包含 read_api 和 read_repository。保存后即可选择仓库,无需重启网站。
已连接时通过「修改连接」更新配置。使用同一地址且令牌留空时保留已有令牌;更换地址时需填写对应的新令牌。验证失败会保留原配置。
工作台是团队共享空间,该连接可访问的仓库、导入源码与报告面向工作台使用者。若页面显示连接由服务器环境变量管理,请由管理员更新服务器配置。
上传源码 ZIP
- 点击「添加项目」,选择「上传 ZIP」。
- 选择源码压缩包,最大支持 50 MB,按页面提示完成上传。
- 上传后确认扫描范围与排除项,再点击「开始扫描」;代码版本按压缩包解压后的内容摘要固定。
- 在项目的「上传代码」中查看问题与报告。
更新源码时,从对应项目点击「上传新版本并扫描」。ZIP 结果单独保存在上传来源中,不混入 Git 分支结果。ZIP 不保留原仓库的提交历史,适合检查一份完整代码。
查看分支结果与验证修复
工作台首页用一句“X 个分支有问题”概括项目情况。点击项目名称并选择分支后,查看检查结论、问题数量、级别、扫描版本与时间。点击「查看 X 个问题」直接进入对应报告的问题区域,在报告内筛选、搜索和阅读详情;工作台不重复展示问题列表。
| 页面状态 | 含义与下一步 |
|---|---|
| 待扫描 / 新版本待扫描 | 当前版本尚未取得完整结果,点击「扫描最新代码」 |
| 等待执行 / 扫描中 / 生成报告中 | 显示当前阶段;点击「查看进度」查看任务详情,执行结束后展示结论 |
| 检查未通过 | 完整扫描发现严重或高等级问题,修复后重新扫描 |
| 所选范围通过/未通过 | 局部扫描已完成,结论只适用于所选目录或文件;上次完整项目扫描结果仍可查看 |
| 检查通过 | 本次待查文件均已完成,且严重、高等级问题为零;中低等级问题仍需阅读和处理 |
| 扫描未完成或待确认 | 计划内仍有未完成文件、文件检查异常、结果证据不足或问题级别未知,先核对提示原因 |
| 无待查文件 | 本次范围没有可检查文件,打开任务详情查看范围明细和排除原因 |
| 最新版本未确认 | 当前无法确认分支最新提交,先恢复仓库连接再检查 |
没有问题记录不等于检查通过。 任务未完成或历史证据不足时,页面会保留待确认状态;没有待查文件时也不会显示通过。缺少适用规则或按设置排除的文件不参与本次检查,页面保留数量与原因;「检查通过」只针对本次待查范围,不代表这些未覆盖文件已检查。
修复后,把修改提交并推送到同一分支,然后点击「扫描最新代码」。先确认或修改上次的范围与排除项,再开始扫描。验证整个项目时选择「整个项目」;查看新结果时再次核对提交标识。上传项目则上传修复后的 ZIP。
新扫描尚未完成时,主区域只显示本次阶段与进度。展开「扫描记录」可查看历史版本、任务详情和报告;缺少分支依据的历史记录归入「未记录分支」。报告尚未生成或生成失败时,从对应任务生成或重试报告,已保存的问题不会丢失。
调整扫描设置
点击项目分支页的「扫描最新代码」,先打开设置。系统按分支带出上次配置,可修改后再点击「开始扫描」;修改不会影响其他分支或历史任务。
- 整个项目 + 排除目录:保留默认范围,在「排除文件或目录」点击「选择文件 / 目录」,勾选第三方源码目录即可递归排除。
- 只查指定范围:切换到「指定目录或文件」,勾选一个或多个路径,也可同时设置排除项。
- 重新扫描时调整:增减勾选项或直接编辑文本;清空排除项即取消排除,切回「整个项目」即取消局部范围。每行一个路径,排除项也支持通配符。
其他设置如下:
| 设置 | 默认值 | 使用说明 |
|---|---|---|
| 文件任务并发 | 8 | 可设 1–20;遇到模型限流时适当降低 |
| 每个任务时限 | 30 分钟 | 可设 0–120;0 表示不限,和整个扫描阶段的时限不同 |
| 扫描 Token 预算 | 0(不限) | 按需要设置用量上限,实际用量以引擎记录为准 |
| 模型 | 沿用网站配置 | 需要指定时,填写当前模型服务支持的模型 ID |
| 扫描组织方式 | 按语言 | 可按语言、按目录或逐文件组织 |
页面还提供业务背景等高级设置。业务背景用于帮助理解项目,不能代替规则库条款。排除路径会改变本次待查范围,范围明细保留排除原因;阅读结论时应同时核对这些未覆盖文件。
代码、规则或配置变化后,应使用新的扫描准备结果。提高并发不一定更快;若模型响应慢或持续限流,应先检查连接、服务容量和任务日志。
选择扫描规则
- 打开规则库,选择项目使用的语言,阅读条款与来源。
- 按项目需要调整已有条款的启用状态,并保存。
- 回到工作台开始新的扫描,使新设置进入本次检查范围。
规则库的搜索与分类只控制页面显示,是否参与扫描由条款开关及文件匹配决定。当前发布的规则为有来源记录的有效内置条款。
一次扫描会固定所用代码、规则和配置。运行中修改开关只影响之后的扫描;已保存的报告继续使用当时的规则快照。没有适用规则的文件会标明“缺少适用规则跳过”,保留未覆盖的文件与原因,但不计为扫描未完成;系统不会为了凑齐覆盖而补写条款。来源可在规则来源核对。
查看进度、用量与执行记录
扫描过程中点击「查看进度」进入任务详情。页面自动更新状态、已检查文件数和文件处理情况,保留展开的范围明细、日志和滚动位置。任务详情只提供当前任务的取消、继续未完成或报告恢复操作;新扫描统一回到项目分支页发起。关闭浏览器不会取消后台扫描。
扫描一般经历准备范围、执行检查、生成报告三个阶段。等待执行表示任务尚在队列中;生成报告表示正在整理已有结果,无需再次调用模型。已检查数依据引擎保存的完成检查点,可能按批次增加;期间会显示正在处理的文件数和当前活动。等待执行时只显示计划文件数,不显示进度条或未完成告警。排除原因保留在范围明细中。
计划内 80/80 完成,表示本次待查文件已全部处理。 缺少规则和按设置排除的文件单独展示,不影响完成状态;可展开范围明细查看哪些文件未参与检查。
Token 用量以保存的执行记录为准。中断时未记录的用量不能当作零;请求次数等指标若没有记录,页面不会补出估算值。扫描中断时按失败恢复处理。
阅读、下载与保存报告
从项目的扫描记录点击「查看报告」,或打开扫描报告选择已生成的报告。建议按以下顺序阅读:
- 核对项目、分支与代码版本,确认阅读的是目标扫描。
- 查看覆盖情况,区分已完成、失败、复用和排除文件。
- 按关键词、文件或原始级别筛选问题,阅读描述、引用代码、规则依据与修复建议。
- 下载需要保存的 HTML 或 JSON,并记录对应扫描版本。
报告保留扫描引擎给出的描述、原始分级和引用。缺失行号或规则引用时会明确显示缺失,网站不补造依据。
「下载 HTML」保存当前已发布报告的快照,离线仍可阅读、搜索和筛选。报告还支持导出筛选结果 JSON、完整扫描报告 JSON,以及打印。打印会展开全部问题和折叠内容,打印结束后恢复阅读状态。
下载后报告不会自动更新;重新生成报告或完成新扫描后,需要另行下载。查看和导出报告不新增模型调用。
使用 AI 解读规则和报告
在具体规则文档或报告中使用 AI 阅读助手。首页和工作台列表没有全文解析入口。
| 操作 | 适用场景 |
|---|---|
| 解析规则 / 提取检查清单 | 理解当前规则文档中的已有要求 |
| 解析报告 / 提取问题清单 | 阅读报告全部问题及其证据 |
| 向 AI 追问 | 深入讨论一条具体问题 |
| 选中文字后使用浮动工具栏 | 解释一段描述或代码 |
打开面板后先确认上方的当前引用,再输入问题并继续追问。全文解析会读取报告全部问题,不随当前筛选缩小范围;只讨论一条问题时使用「向 AI 追问」。
需要中断回答时点击「停止生成」,需要保存时点击「复制」。关闭面板只是收起界面;刷新或离开页面会中断当前阅读请求,后台扫描仍独立运行。
AI 回答用于辅助理解,应对照原条款、问题编号和代码核实。提取检查清单不会新增扫描规则,回答也不会直接修改代码或报告。对话保存在当前浏览器,换设备或清理网站数据后不会自动恢复。提问会调用已配置的模型服务,重试可能产生额外用量。
失败恢复与常见问题
| 遇到的情况 | 处理方法 |
|---|---|
| GitLab 仓库找不到或导入失败 | 核对仓库链接、分支和团队账号读取权限;管理员验证 GitLab 连接 |
| 提示 AI 未配置、认证失败或模型不存在 | 管理员核对接口协议、模型 ID、密钥及实际配置文件,重启后验证连接 |
| 没有待查文件 | 检查代码范围、排除设置和适用规则;空计划不表示通过 |
| 扫描失败、中断或部分完成 | 打开任务详情查看原因;会话可用且固定输入兼容时点击「继续未完成」 |
| 模型限流、超时或预算不足 | 先处理日志中提示的原因;改变设置或代码后发起新的扫描 |
| 代码已经修复 | GitLab 项目点击「扫描最新代码」;ZIP 项目点击「上传新版本并扫描」 |
| 检查完成但报告生成失败 | 点击「重新生成报告」,无需重新扫描代码或调用模型 |
| 新扫描时仍看到旧问题 | 查看是否标注「上次完整扫描」,进入本次任务查看进度与部分结果 |
| AI 配置已加载但提问失败 | 已加载只表示配置被读取,还需验证模型服务能实际响应 |
「继续未完成」用于补齐原版本的中断检查,会核对源码、规则、模型、范围与引擎的兼容性,并保留原失败记录。修复后的验证应重新扫描最新代码,不能把旧会话中未再次报告的问题直接视为已修复。
管理员准备与日常维护
已有可用网站的团队成员可以直接使用工作台。首次部署时,管理员准备 Python 3.10+、Git、匹配平台的官方扫描引擎和报告工具;从源码构建两个工具时还需安装各自要求版本的 Go。
首次从源码启动
在项目目录执行,将路径替换为实际位置:
cd /path/to/ocr-web
bash ocr-engine/scripts/build.sh
bash ocr-report-renderer/scripts/build.sh
python3 -m ocr_workbench build
bash start.sh
python3 -m ocr_workbench status浏览器打开 http://服务器IP:8085/workspace。网站发布包若已包含构建产物,可直接启动。默认监听 0.0.0.0:8085,地址与端口可通过 OCR_WEB_HOST、OCR_WEB_PORT 设置。
配置网站模型连接
使用 bash start.sh 启动时,默认配置文件为 ~/.config/ocr-web/ai.json;仓库部署脚本管理的服务使用 /var/lib/ocr-web/ai.json。若设置了 OCR_AI_CONFIG,以指定路径为准。
以下是网站支持的 Chat Completions 兼容接口配置示例,把占位值替换为实际服务信息:
{
"provider": "openai",
"OPENAI_BASE_URL": "https://your-proxy.example/v1",
"OPENAI_MODEL": "YOUR_MODEL_ID",
"OPENAI_API_KEY": "YOUR_API_KEY"
}按模型服务实际支持的协议填写配置。设置文件权限为 600,然后使用运行网站的同一用户检查配置并重启:
python3 -m ocr_workbench ai check
bash stop.sh
bash start.sh由 systemd 管理的服务使用 sudo systemctl restart ocr-web 重启。配置检查只验证字段,启用后应打开具体规则页面发起一次提问,确认实际连接可用。其他协议模板和服务配置见AI 配置。
工作台扫描与网页阅读默认共用这份连接;浏览器不需要填写模型密钥。独立终端中的 OCR 命令使用自己的配置。
默认运行数据保存在 var/,可用 OCR_DATA_DIR 更改;网站日志在数据目录的 log/server.log。备份时一起保存任务数据库、代码快照、会话、报告和实际配置。历史报告保留原版本,重新构建网站文档不会改写扫描结果。