跳到正文
Code Review
首页 / 文档中心 / 使用手册

文档中心 · 使用指南

使用手册

从导入项目开始,完成分支扫描、问题定位、修复复扫和报告保存。按页面上的实际操作,一篇手册用好 ocr-web。

使用手册更新于 2026-11-20正文约 9 分钟

先看结论

  1. 01

    选好代码即可扫描

    打开工作台,选择 GitLab 仓库与分支,或上传源码 ZIP,点击「下一步:扫描设置」,确认范围后开始扫描。

  2. 02

    按分支查看问题

    每个分支分别展示扫描版本、结果摘要和扫描记录;问题详情统一在对应报告中查看。

  3. 03

    修复后扫描最新代码

    提交修复后确认范围并重新扫描;中断恢复使用「继续未完成」,报告生成失败可以单独重试。

从哪里开始

ocr-web 用于在网页上检查代码、管理规则和阅读扫描结果。日常使用从工作台开始;管理员需要提前准备模型连接和扫描工具。

你要做什么入口与操作
第一次检查项目工作台 → 添加项目 → 连接 GitLab 或上传 ZIP
查看某个分支的问题打开项目 → 选择分支 → 查看问题(进入对应报告)
修复后重新检查将修复提交到原分支 → 扫描最新代码
调整扫描参数项目分支页 → 扫描最新代码 → 确认设置
选择参与扫描的已有条款规则库 → 对应语言 → 调整开关并保存
阅读或保存完整结果项目中的查看报告,或扫描报告
第一次安装或连接模型本文的管理员准备
流程图一次完整的使用流程
  1. 01导入代码选择 GitLab 分支或上传源码 ZIP
  2. 02执行扫描等待代码检查与报告生成
  3. 03查看问题核对版本、覆盖与问题详情
  4. 04修复复扫提交修改后扫描最新代码
  5. 05保存报告下载需要保留的结果

导入 GitLab 项目

  1. 在工作台点击「添加项目」,选择「连接 GitLab」。
  2. 搜索仓库名称,或粘贴仓库链接,选择需要检查的仓库。
  3. 选择分支。页面默认选择仓库的默认分支,也可以搜索其他分支。
  4. 点击「下一步:扫描设置」,选择范围与排除项,再点击「开始扫描」。系统固定代码提交并按设置准备待查文件。
  5. 进入项目页查看进度;完成后查看分支结果摘要,点击「查看问题」进入对应报告。

同一个仓库复用一个项目。检查其他分支时,在项目页点击「选择分支 / 上传代码」。各分支分别保存问题与扫描记录,查看结果时先核对分支名称和扫描版本。

首次使用:管理员配置团队 GitLab

在「添加项目 → 连接 GitLab」中点击「配置连接」,填写团队 GitLab 地址与访问令牌,然后点击「验证并保存」。团队账号需要具有目标仓库的读取权限,令牌需要包含 read_api 和 read_repository。保存后即可选择仓库,无需重启网站。

已连接时通过「修改连接」更新配置。使用同一地址且令牌留空时保留已有令牌;更换地址时需填写对应的新令牌。验证失败会保留原配置。

工作台是团队共享空间,该连接可访问的仓库、导入源码与报告面向工作台使用者。若页面显示连接由服务器环境变量管理,请由管理员更新服务器配置。

上传源码 ZIP

  1. 点击「添加项目」,选择「上传 ZIP」。
  2. 选择源码压缩包,最大支持 50 MB,按页面提示完成上传。
  3. 上传后确认扫描范围与排除项,再点击「开始扫描」;代码版本按压缩包解压后的内容摘要固定。
  4. 在项目的「上传代码」中查看问题与报告。

更新源码时,从对应项目点击「上传新版本并扫描」。ZIP 结果单独保存在上传来源中,不混入 Git 分支结果。ZIP 不保留原仓库的提交历史,适合检查一份完整代码。

查看分支结果与验证修复

工作台首页用一句“X 个分支有问题”概括项目情况。点击项目名称并选择分支后,查看检查结论、问题数量、级别、扫描版本与时间。点击「查看 X 个问题」直接进入对应报告的问题区域,在报告内筛选、搜索和阅读详情;工作台不重复展示问题列表。

页面状态含义与下一步
待扫描 / 新版本待扫描当前版本尚未取得完整结果,点击「扫描最新代码」
等待执行 / 扫描中 / 生成报告中显示当前阶段;点击「查看进度」查看任务详情,执行结束后展示结论
检查未通过完整扫描发现严重或高等级问题,修复后重新扫描
所选范围通过/未通过局部扫描已完成,结论只适用于所选目录或文件;上次完整项目扫描结果仍可查看
检查通过本次待查文件均已完成,且严重、高等级问题为零;中低等级问题仍需阅读和处理
扫描未完成或待确认计划内仍有未完成文件、文件检查异常、结果证据不足或问题级别未知,先核对提示原因
无待查文件本次范围没有可检查文件,打开任务详情查看范围明细和排除原因
最新版本未确认当前无法确认分支最新提交,先恢复仓库连接再检查

没有问题记录不等于检查通过。 任务未完成或历史证据不足时,页面会保留待确认状态;没有待查文件时也不会显示通过。缺少适用规则或按设置排除的文件不参与本次检查,页面保留数量与原因;「检查通过」只针对本次待查范围,不代表这些未覆盖文件已检查。

修复后,把修改提交并推送到同一分支,然后点击「扫描最新代码」。先确认或修改上次的范围与排除项,再开始扫描。验证整个项目时选择「整个项目」;查看新结果时再次核对提交标识。上传项目则上传修复后的 ZIP。

新扫描尚未完成时,主区域只显示本次阶段与进度。展开「扫描记录」可查看历史版本、任务详情和报告;缺少分支依据的历史记录归入「未记录分支」。报告尚未生成或生成失败时,从对应任务生成或重试报告,已保存的问题不会丢失。

调整扫描设置

点击项目分支页的「扫描最新代码」,先打开设置。系统按分支带出上次配置,可修改后再点击「开始扫描」;修改不会影响其他分支或历史任务。

  • 整个项目 + 排除目录:保留默认范围,在「排除文件或目录」点击「选择文件 / 目录」,勾选第三方源码目录即可递归排除。
  • 只查指定范围:切换到「指定目录或文件」,勾选一个或多个路径,也可同时设置排除项。
  • 重新扫描时调整:增减勾选项或直接编辑文本;清空排除项即取消排除,切回「整个项目」即取消局部范围。每行一个路径,排除项也支持通配符。

其他设置如下:

设置默认值使用说明
文件任务并发8可设 1–20;遇到模型限流时适当降低
每个任务时限30 分钟可设 0–120;0 表示不限,和整个扫描阶段的时限不同
扫描 Token 预算0(不限)按需要设置用量上限,实际用量以引擎记录为准
模型沿用网站配置需要指定时,填写当前模型服务支持的模型 ID
扫描组织方式按语言可按语言、按目录或逐文件组织

页面还提供业务背景等高级设置。业务背景用于帮助理解项目,不能代替规则库条款。排除路径会改变本次待查范围,范围明细保留排除原因;阅读结论时应同时核对这些未覆盖文件。

代码、规则或配置变化后,应使用新的扫描准备结果。提高并发不一定更快;若模型响应慢或持续限流,应先检查连接、服务容量和任务日志。

选择扫描规则

  1. 打开规则库,选择项目使用的语言,阅读条款与来源。
  2. 按项目需要调整已有条款的启用状态,并保存。
  3. 回到工作台开始新的扫描,使新设置进入本次检查范围。

规则库的搜索与分类只控制页面显示,是否参与扫描由条款开关及文件匹配决定。当前发布的规则为有来源记录的有效内置条款。

一次扫描会固定所用代码、规则和配置。运行中修改开关只影响之后的扫描;已保存的报告继续使用当时的规则快照。没有适用规则的文件会标明“缺少适用规则跳过”,保留未覆盖的文件与原因,但不计为扫描未完成;系统不会为了凑齐覆盖而补写条款。来源可在规则来源核对。

查看进度、用量与执行记录

扫描过程中点击「查看进度」进入任务详情。页面自动更新状态、已检查文件数和文件处理情况,保留展开的范围明细、日志和滚动位置。任务详情只提供当前任务的取消、继续未完成或报告恢复操作;新扫描统一回到项目分支页发起。关闭浏览器不会取消后台扫描。

扫描一般经历准备范围、执行检查、生成报告三个阶段。等待执行表示任务尚在队列中;生成报告表示正在整理已有结果,无需再次调用模型。已检查数依据引擎保存的完成检查点,可能按批次增加;期间会显示正在处理的文件数和当前活动。等待执行时只显示计划文件数,不显示进度条或未完成告警。排除原因保留在范围明细中。

计划内 80/80 完成,表示本次待查文件已全部处理。 缺少规则和按设置排除的文件单独展示,不影响完成状态;可展开范围明细查看哪些文件未参与检查。

Token 用量以保存的执行记录为准。中断时未记录的用量不能当作零;请求次数等指标若没有记录,页面不会补出估算值。扫描中断时按失败恢复处理。

阅读、下载与保存报告

从项目的扫描记录点击「查看报告」,或打开扫描报告选择已生成的报告。建议按以下顺序阅读:

  1. 核对项目、分支与代码版本,确认阅读的是目标扫描。
  2. 查看覆盖情况,区分已完成、失败、复用和排除文件。
  3. 按关键词、文件或原始级别筛选问题,阅读描述、引用代码、规则依据与修复建议。
  4. 下载需要保存的 HTML 或 JSON,并记录对应扫描版本。

报告保留扫描引擎给出的描述、原始分级和引用。缺失行号或规则引用时会明确显示缺失,网站不补造依据。

「下载 HTML」保存当前已发布报告的快照,离线仍可阅读、搜索和筛选。报告还支持导出筛选结果 JSON、完整扫描报告 JSON,以及打印。打印会展开全部问题和折叠内容,打印结束后恢复阅读状态。

下载后报告不会自动更新;重新生成报告或完成新扫描后,需要另行下载。查看和导出报告不新增模型调用。

使用 AI 解读规则和报告

在具体规则文档或报告中使用 AI 阅读助手。首页和工作台列表没有全文解析入口。

操作适用场景
解析规则 / 提取检查清单理解当前规则文档中的已有要求
解析报告 / 提取问题清单阅读报告全部问题及其证据
向 AI 追问深入讨论一条具体问题
选中文字后使用浮动工具栏解释一段描述或代码

打开面板后先确认上方的当前引用,再输入问题并继续追问。全文解析会读取报告全部问题,不随当前筛选缩小范围;只讨论一条问题时使用「向 AI 追问」。

需要中断回答时点击「停止生成」,需要保存时点击「复制」。关闭面板只是收起界面;刷新或离开页面会中断当前阅读请求,后台扫描仍独立运行。

AI 回答用于辅助理解,应对照原条款、问题编号和代码核实。提取检查清单不会新增扫描规则,回答也不会直接修改代码或报告。对话保存在当前浏览器,换设备或清理网站数据后不会自动恢复。提问会调用已配置的模型服务,重试可能产生额外用量。

失败恢复与常见问题

遇到的情况处理方法
GitLab 仓库找不到或导入失败核对仓库链接、分支和团队账号读取权限;管理员验证 GitLab 连接
提示 AI 未配置、认证失败或模型不存在管理员核对接口协议、模型 ID、密钥及实际配置文件,重启后验证连接
没有待查文件检查代码范围、排除设置和适用规则;空计划不表示通过
扫描失败、中断或部分完成打开任务详情查看原因;会话可用且固定输入兼容时点击「继续未完成」
模型限流、超时或预算不足先处理日志中提示的原因;改变设置或代码后发起新的扫描
代码已经修复GitLab 项目点击「扫描最新代码」;ZIP 项目点击「上传新版本并扫描」
检查完成但报告生成失败点击「重新生成报告」,无需重新扫描代码或调用模型
新扫描时仍看到旧问题查看是否标注「上次完整扫描」,进入本次任务查看进度与部分结果
AI 配置已加载但提问失败已加载只表示配置被读取,还需验证模型服务能实际响应

「继续未完成」用于补齐原版本的中断检查,会核对源码、规则、模型、范围与引擎的兼容性,并保留原失败记录。修复后的验证应重新扫描最新代码,不能把旧会话中未再次报告的问题直接视为已修复。

管理员准备与日常维护

已有可用网站的团队成员可以直接使用工作台。首次部署时,管理员准备 Python 3.10+、Git、匹配平台的官方扫描引擎和报告工具;从源码构建两个工具时还需安装各自要求版本的 Go。

首次从源码启动

在项目目录执行,将路径替换为实际位置:

bash
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 兼容接口配置示例,把占位值替换为实际服务信息:

json
{
  "provider": "openai",
  "OPENAI_BASE_URL": "https://your-proxy.example/v1",
  "OPENAI_MODEL": "YOUR_MODEL_ID",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

按模型服务实际支持的协议填写配置。设置文件权限为 600,然后使用运行网站的同一用户检查配置并重启:

bash
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。备份时一起保存任务数据库、代码快照、会话、报告和实际配置。历史报告保留原版本,重新构建网站文档不会改写扫描结果。