从你当前的情况开始
| 当前情况 | 下一步 |
|---|---|
| 网站已上线,只需要接入或更换模型 | 从确认配置文件开始,修改后按连接验证启用 |
| 日常使用工作台或阅读报告 | 直接看工作台快速开始或AI 使用说明,无需安装命令 |
| 第一次部署网站 | 依次完成环境准备、安装启动、模型连接与工作台设置 |
| 已使用仓库部署脚本管理公网服务 | 使用 /var/lib/ocr-web/ai.json 和 systemctl,按服务用户检查配置 |
本页面向管理员。网站不会在此页编辑或回显密钥;状态卡仅显示当前加载的协议、模型与配置状态。
准备环境
以下操作都在已经登录的 Ubuntu 22.04 及以上服务器执行,直接使用当前登录用户。 先取得完整的 ocr-web 项目目录或网站发布包,并放到服务器上。
安装 Python 3.10+ 和常用工具。若当前已是 root,可省略命令中的 sudo:
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 仍使用自己的配置。
- 01准备运行环境Python、Git、项目文件、官方引擎与报告工具
- 02构建并启动先确认网站可访问
- 03配置模型写入配置文件,检查后重启
- 04启用工作台上传或登记项目,预览验证范围
- 05备份与维护一起保存任务、代码快照、会话与报告
安装并启动
进入项目目录,构建并启动。把 /path/to/ocr-web 换成你的实际路径:
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 放在同一目录,在该目录执行。请使用新的安装目录:
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.json | ocr-web 用户;sudo systemctl restart ocr-web |
已通过部署脚本上线:编辑服务的配置文件
使用 start.sh 启动:编辑当前用户的配置文件
使用启动网站的同一用户创建文件:
mkdir -p ~/.config/ocr-web
chmod 700 ~/.config/ocr-web
vi ~/.config/ocr-web/ai.json将下一节的 JSON 填入文件并保存,然后设置权限:
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 接口:
{
"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 和密钥:
{
"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 启动时,在项目目录、以同一用户执行:
python3 -m ocr_workbench ai check && bash stop.sh && bash start.sh通过 deploy/deploy.sh 部署的公网服务
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 配置已加载」,表示当前进程已读取字段,不能据此判断密钥、模型或上游服务已实际可用。
如需验证接口实际可用,执行下面的命令,会发送一次简短模型请求:
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。仅供阅读的网站发布包不包含这两个程序;可由维护者生成包含引擎的一体化包:
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 为冒号):
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/,无需重启:
mkdir -p var/reports
cp /path/to/review.html var/reports/文件名以 .html 结尾,放在该目录第一层;覆盖同名文件前先备份。生成报告见 OCR CLI 使用手册。
可选:开机自启
通过仓库 deploy/deploy.sh 部署时已经配置开机自启,使用现有服务即可。下面仅适用于通过 start.sh 安装、准备转为 systemd 的单目录部署,仍使用当前用户、现有项目目录和同一份 AI 配置。
使用 systemd 设置开机自启
在项目目录中,以前面启动网站的用户执行整段命令。命令会自动填入当前用户名和目录,先停止脚本启动的进程,再启用 systemd:
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 配置后,在项目目录检查并重启:
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.log | journalctl -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 配置。然后在项目目录执行:
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。