跳到正文
Code Review
AI 助手 / 安装与 AI 配置

AI 助手 · 配置指南

OCR Workbench 安装与 AI 配置

已有网站先确认配置路径、连接模型并验证响应;首次安装再准备网站、扫描引擎与报告工具。

安装与配置更新于 2026-11-18正文约 11 分钟

先看结论

  1. 01

    已有网站先配置

    确认实际配置路径,填写接口协议、模型 ID 和密钥,再检查并重启。

  2. 02

    配置加载后验证响应

    配置检查只验证字段;实际连接需要一次模型请求确认。

  3. 03

    按目的进入功能

    工作台执行代码检查,AI 助手解读规则与报告,两者默认共用模型连接。

从你当前的情况开始

当前情况下一步
网站已上线,只需要接入或更换模型从确认配置文件开始,修改后按连接验证启用
日常使用工作台或阅读报告直接看工作台快速开始或AI 使用说明,无需安装命令
第一次部署网站依次完成环境准备、安装启动、模型连接与工作台设置
已使用仓库部署脚本管理公网服务使用 /var/lib/ocr-web/ai.json 和 systemctl,按服务用户检查配置

本页面向管理员。网站不会在此页编辑或回显密钥;状态卡仅显示当前加载的协议、模型与配置状态。

准备环境

以下操作都在已经登录的 Ubuntu 22.04 及以上服务器执行,直接使用当前登录用户。 先取得完整的 ocr-web 项目目录或网站发布包,并放到服务器上。

安装 Python 3.10+ 和常用工具。若当前已是 root,可省略命令中的 sudo:

bash
sudo apt-get update
sudo apt-get install -y python3 curl tar git
python3 --version

网站运行只需要 Python 标准库。本篇供管理员使用;日常网页扫描见快速开始,独立终端扫描见 OCR CLI 使用手册,网页提问操作见 AI 使用说明。工作台将生效规则传给官方 OCR,并用独立 ocr-report-renderer 生成报告。网页扫描复用网站 AI 配置;独立 CLI 仍使用自己的配置。

流程图管理员的一次准备
  1. 01准备运行环境Python、Git、项目文件、官方引擎与报告工具
  2. 02构建并启动先确认网站可访问
  3. 03配置模型写入配置文件,检查后重启
  4. 04启用工作台上传或登记项目,预览验证范围
  5. 05备份与维护一起保存任务、代码快照、会话与报告

安装并启动

进入项目目录,构建并启动。把 /path/to/ocr-web 换成你的实际路径:

bash
cd /path/to/ocr-web
python3 -m ocr_workbench build
bash start.sh
python3 -m ocr_workbench status
如果拿到的是网站发布包

将 ocr-workbench.tar.gz 和 ocr-workbench.tar.gz.sha256 放在同一目录,在该目录执行。请使用新的安装目录:

bash
sha256sum -c ocr-workbench.tar.gz.sha256
mkdir -p "$HOME/ocr-web"
tar -xzf ocr-workbench.tar.gz -C "$HOME/ocr-web"
cd "$HOME/ocr-web"
bash start.sh
python3 -m ocr_workbench status

发布包已包含构建结果,可以直接启动。

浏览器打开 http://服务器IP:8085,将「服务器IP」替换为这台 Ubuntu 的实际地址。网站默认监听 0.0.0.0:8085,关闭终端后仍会运行;服务器重启后需再次执行 bash start.sh,也可按需设置开机自启。

做到这里即可浏览规则和已有报告。 要在网页扫描代码,继续配置模型并完成工作台设置。

确认并编辑 AI 配置文件

先确认网站怎样启动,再修改对应文件。下面列出项目两种标准启动方式;若设置了 OCR_AI_CONFIG,以该变量指定的路径为准。

启动方式默认配置位置运行用户与重启方式
项目目录执行 bash start.sh~/.config/ocr-web/ai.json启动脚本的用户;bash stop.sh 后 bash start.sh
仓库 deploy/deploy.sh 部署的服务/var/lib/ocr-web/ai.jsonocr-web 用户;sudo systemctl restart ocr-web
已通过部署脚本上线:编辑服务的配置文件

在服务器上使用有管理权限的账号执行:

bash
sudoedit /var/lib/ocr-web/ai.json
sudo chown ocr-web:ocr-web /var/lib/ocr-web/ai.json
sudo chmod 600 /var/lib/ocr-web/ai.json

将模型配置模板填入文件后,按检查并启用 AI验证。以 root 登录服务器时,root 自己的 ~/.config/ocr-web/ai.json 并不是该服务默认读取的文件。

使用 start.sh 启动:编辑当前用户的配置文件

使用启动网站的同一用户创建文件:

bash
mkdir -p ~/.config/ocr-web
chmod 700 ~/.config/ocr-web
vi ~/.config/ocr-web/ai.json

将下一节的 JSON 填入文件并保存,然后设置权限:

bash
chmod 600 ~/.config/ocr-web/ai.json

工作台会将网站连接传给扫描引擎,无需再次执行 ocr config provider。独立 CLI 使用自己的 ~/.opencodereview/config.json,配置方法见 CLI 使用手册。

网页对话默认也使用这份配置中的模型。需要单独指定对话模型时,可在启动环境设置 OCR_WEB_CHAT_MODEL,该模型仍使用配置中的接口与协议。网页默认不额外发送 thinking 参数;确认 Anthropic 兼容模型支持后,可显式设置 OCR_WEB_THINKING_BUDGET=1024。环境配置修改后需重启网站。

填写模型信息

当前运行状态

配置在服务启动时加载。启用 JavaScript 后可查看当前协议与模型。

文件管理 · 重启生效

按接口实际支持的协议选择 provider,将示例地址、模型 ID 和密钥替换为服务商提供的值。模型名称本身不能决定接口协议。

使用 OpenAI 兼容 Chat Completions 接口:

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

此方式调用 Chat Completions 接口。JSON 使用双引号,不支持注释或末尾逗号。

使用 Anthropic Messages 兼容接口

将文件内容换成以下 JSON,并替换接口地址、模型 ID 和密钥:

json
{
  "provider": "anthropic",
  "ANTHROPIC_BASE_URL": "https://your-claude-proxy.example",
  "ANTHROPIC_MODEL": "YOUR_MODEL_ID",
  "ANTHROPIC_AUTH_TOKEN": "YOUR_AUTH_TOKEN"
}

中转需支持 Anthropic Messages 协议和 Authorization: Bearer 认证。模型 ID 以服务商实际支持的为准。

检查并启用 AI

先等待工作台中正在执行的检查结束,再按启动方式检查和重启。重启会中断未完成任务。

使用 start.sh 启动时,在项目目录、以同一用户执行:

bash
python3 -m ocr_workbench ai check && bash stop.sh && bash start.sh
通过 deploy/deploy.sh 部署的公网服务
bash
cd /srv/ocr-web/current
sudo -u ocr-web python3 -m ocr_workbench ai check --config /var/lib/ocr-web/ai.json
sudo systemctl restart ocr-web
sudo systemctl is-active ocr-web

仅在 ai check 成功后重启。自建 systemd 服务使用其实际工作目录、运行用户和配置路径;不要另行运行 start.sh 创建第二个实例。

check 只检查配置,不调用模型。重启后,页面模型信息显示「AI 配置已加载」,表示当前进程已读取字段,不能据此判断密钥、模型或上游服务已实际可用。

如需验证接口实际可用,执行下面的命令,会发送一次简短模型请求:

bash
python3 -m ocr_workbench ai test

部署脚本管理的服务则在 /srv/ocr-web/current 执行 sudo -u ocr-web python3 -m ocr_workbench ai test --config /var/lib/ocr-web/ai.json。命令应使用与服务一致的环境;设置了独立对话模型时,还需在网页确认实际使用的模型能正常响应。

最后打开一份规则文档或扫描报告,发起一次简短提问,确认能收到回答。模型测试与网页提问会产生服务商用量;日常操作见 AI 使用说明。

启用网页扫描工作台

代码与执行器位于运行网站的同一台机器。 工作台调用官方 OCR 完成扫描,再用独立报告工具导出并登记到报告中心。

使用完整项目目录时,先构建两个独立程序:bash ocr-engine/scripts/build.sh 与 bash ocr-report-renderer/scripts/build.sh。若另行安装了官方 OCR,可设置 OCR_BIN=/absolute/path/to/ocr;独立报告工具用 OCR_REPORT_BIN=/absolute/path/to/ocr-report-renderer。仅供阅读的网站发布包不包含这两个程序;可由维护者生成包含引擎的一体化包:

bash
python3 -m ocr_workbench build
python3 -m ocr_workbench package workspace --platform linux-amd64

输出为 dist/releases/workspace/ocr-workbench-linux-amd64.tar.gz 和摘要文件。ARM Ubuntu 使用 linux-arm64,macOS 使用 darwin-arm64 或 darwin-amd64。目标机器解压后直接运行 bash start.sh,无需 Go 编译环境。打包前运行两个构建脚本的 --all 准备对应平台程序;工作台包同时包含扫描器和报告工具。

安装引擎和上文模型配置后,打开工作台即可直接使用。能访问网站的用户可以登记项目、查看任务并启动扫描;需要限制访问人员时,由部署环境的网络或反向代理控制网站访问。

用户点击「添加项目」,选择「连接 GitLab」或「上传 ZIP」,再点击「继续,设置检查」。选择完整代码扫描或 Git 提交、分支评审,确认范围后点击「开始检查」。上传 ZIP 上限 50 MB,解压后 200 MB、10,000 个条目,单文件 20 MB;ZIP 仅支持完整代码扫描。源码由网站管理,不执行项目代码。结果自动进入扫描报告,不需要手工导出、复制文件或重启网站。

首次使用 GitLab 时,由管理员在「连接 GitLab」中点击「配置连接」,填写实际 GitLab 地址和具备 read_api、read_repository 权限的令牌,验证成功后保存。令牌仅保存在服务器的数据目录 gitlab.json,不会回显;团队成员随后选择仓库和分支即可。已有连接通过「修改连接」更新,同一地址下令牌留空会沿用已保存值。配置由 OCR_GITLAB_* 环境变量管理时,页面只读。

工作台与扫描均使用网站进程的运行用户,需要能够保存受管源码和 OCR 会话。旧本地仓库记录继续保留;如需限制兼容接口可登记的本地目录,在启动前设置允许的目录根,多个目录使用系统路径分隔符(Ubuntu/macOS 为冒号):

bash
export OCR_WORKSPACE_ROOTS='/home/team/projects:/srv/code'
bash start.sh

不设置时,兼容接口允许登记运行用户能够读取的 Git 仓库;设置后拒绝超出限制的项目真实路径。当前网页添加项目使用 GitLab 或 ZIP。systemd 部署将对应环境变量写入服务配置。

项目、版本、检查、执行记录、规则快照和日志保存在数据目录下的 workspace/。

网站重启会把未完成的任务标为「已中断」,已有报告继续可读;原源码身份一致且有可用会话时,可继续未完成扫描。报告导出有独立恢复入口,不调用模型。任务运行期间关闭浏览器不会停止扫描。

默认累计 Token 预算 0 表示不限,文件任务并发 8、每任务 30 分钟;请求和无进度超时独立生效。扫描与纯导出分别排队,报告发布后任务结束;并发、限流和超时设置见性能与用量。日常操作见快速开始。

日常启停与报告

始终在同一项目目录、使用同一用户执行。已设置开机自启时,使用该节的 systemctl 命令:

操作命令
查看状态python3 -m ocr_workbench status
停止网站bash stop.sh
启动网站bash start.sh
重启网站bash stop.sh && bash start.sh
查看日志tail -n 50 var/log/server.log

工作台生成的报告会自动出现在列表,无需手动操作。 兼容已有单文件 HTML 报告时,可由管理员放入 var/reports/,无需重启:

bash
mkdir -p var/reports
cp /path/to/review.html var/reports/

文件名以 .html 结尾,放在该目录第一层;覆盖同名文件前先备份。生成报告见 OCR CLI 使用手册。

可选:开机自启

通过仓库 deploy/deploy.sh 部署时已经配置开机自启,使用现有服务即可。下面仅适用于通过 start.sh 安装、准备转为 systemd 的单目录部署,仍使用当前用户、现有项目目录和同一份 AI 配置。

使用 systemd 设置开机自启

在项目目录中,以前面启动网站的用户执行整段命令。命令会自动填入当前用户名和目录,先停止脚本启动的进程,再启用 systemd:

bash
bash stop.sh
sudo tee /etc/systemd/system/ocr-web.service >/dev/null <<EOF
[Unit]
Description=OCR Workbench
After=network.target

[Service]
Type=simple
User=$(id -un)
WorkingDirectory=$PWD
Environment="OCR_AI_CONFIG=$HOME/.config/ocr-web/ai.json"
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/bin/python3 -m ocr_workbench serve --host 0.0.0.0 --port 8085
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now ocr-web
sudo systemctl status ocr-web --no-pager

此后用以下命令管理服务;start.sh、stop.sh 和 ocr_workbench status 只管理脚本启动的实例,不适用于 systemd:

操作命令
查看状态sudo systemctl status ocr-web --no-pager
停止网站sudo systemctl stop ocr-web
启动网站sudo systemctl start ocr-web
重启网站sudo systemctl restart ocr-web
查看日志sudo journalctl -u ocr-web -n 50 --no-pager

修改 AI 配置后,在项目目录检查并重启:

bash
python3 -m ocr_workbench ai check && sudo systemctl restart ocr-web

本例使用默认配置和数据路径。网站仍通过 http://服务器IP:8085 访问,报告仍放在项目的 var/reports/ 中。保持项目目录位置不变。

配置与数据放在哪里

内容start.sh 默认位置deploy/deploy.sh 标准部署
网站 AI 配置~/.config/ocr-web/ai.json/var/lib/ocr-web/ai.json
HTML 报告项目内 var/reports//var/lib/ocr-web/reports/
项目、任务、规则快照和日志项目内 var/workspace//var/lib/ocr-web/workspace/
原始 OCR 扫描会话运行用户的 ~/.opencodereview/sessions//var/lib/ocr-web/.opencodereview/sessions/
规则开关状态项目内 var/state/rule-state.json/var/lib/ocr-web/rule-state.json
服务日志项目内 var/log/server.logjournalctl -u ocr-web
需要自定义路径或环境变量时再看
环境变量用途
OCR_AI_CONFIG指定 AI 配置文件
OCR_DATA_DIR修改数据根目录,默认是项目内的 var
OCR_REPORT_DIR单独指定报告目录
OCR_RULE_STATE_FILE单独指定规则开关文件
OCR_WEB_HOST、OCR_WEB_PORT修改脚本启动时的监听地址和端口

显式的报告、规则状态路径优先于 OCR_DATA_DIR。JSON 文件中的字段优先于同名环境变量。修改后重启生效;检查、启停和查询状态时使用相同环境。仓库部署的服务可在 /etc/ocr-web/environment 中设置环境覆盖;修改服务定义后需先执行 sudo systemctl daemon-reload。

更新与备份

仓库部署脚本会备份持久数据、验证发布包并检查服务状态;日常发布前仍需等待活动任务完成。该方式应备份 /var/lib/ocr-web/ 和 /etc/ocr-web/environment,保留旧版本及发布备份。下面的手动更新步骤适用于单目录安装。

更新前先查看工作台是否还有运行任务;停止服务会中断未完成阶段。备份项目内完整的 var/、~/.config/ocr-web/ai.json 和网站运行用户的 ~/.opencodereview/sessions/(如已创建),并保留旧版项目以便恢复。

会话目录需连同源码快照、检查点和报告输入等伴随文件一起备份,不能只取一个会话 JSON 或一份 HTML。var/workspace/ 包含任务、规则快照、上传的受管仓库和固定引擎等运行资料;若用了自定义目录,备份实际路径。外部登记的仓库也需独立保留。

将新源码或发布包中的应用文件更新到原项目目录,保留已有 var/ 数据和 AI 配置。然后在项目目录执行:

bash
python3 -m ocr_workbench build && bash start.sh

若已配置 systemd,停止用 sudo systemctl stop ocr-web,更新后执行 python3 -m ocr_workbench build && sudo systemctl start ocr-web。

更新完成后打开网站,确认规则、报告和 AI 状态正常。需要迁移到另一台服务器时,复制项目、var/ 数据、AI 配置及原始 OCR 会话,跳过旧的 var/run/ 进程记录,再按本文启动。原任务继续导出需要对应用户的会话与原仓库绝对路径;项目路径变化时重新登记项目,已有 HTML 报告仍可阅读。

常见问题

现象处理方法
Python 不存在或版本过旧用 python3 --version 确认版本为 3.10+
提示先构建或页面缺失在项目目录执行 python3 -m ocr_workbench build
网站启动失败查看日志,确认 8085 端口未被其他实例占用
本机能访问,其他电脑打不开确认访问地址为 http://服务器IP:8085,服务监听 0.0.0.0
AI 配置检查失败检查 JSON、模型、密钥和文件权限,使用启动网站的同一用户检查
AI 返回 401 / 403检查密钥与中转认证方式;Anthropic 示例需支持 Bearer token
AI 返回 404 或连接超时核对 API 地址、接口协议、模型 ID,以及服务器到模型接口的网络
修改 AI 后没有生效先区分用户目录与 /var/lib/ocr-web/ai.json;使用服务实际用户检查,成功后重启
状态显示配置已加载,但提问失败继续测试真实模型响应;配置字段有效不代表接口可用
报告列表没有文件检查 var/reports/ 第一层是否有可读取的 .html 文件

实现依据

管理员核对入口

启动与打包:ocr_workbench/cli.py、ocr_workbench/build/package.py;模型读取:ocr_workbench/web/ai.py;工作台参数:ocr_workbench/workspace/engine.py;上传:ocr_workbench/workspace/uploads.py;任务、恢复与报告发布:ocr_workbench/workspace/manager.py。