Admin:部署与管理 Server

可选阅读

本页面向需要在服务器上部署 Loci Server 的管理员。只在本机维护个人文档库时,可以跳过本页。

部署 Loci Server 后,你可以集中抓取公开文档,并将只读快照提供给团队成员或其他用户。

Loci Server 不接收用户的本地文档。它只抓取无需登录即可访问的公开 HTTP/HTTPS 文档,并发布管理员选定的文档库。

部署 Loci Server

仓库根目录提供了生产环境使用的 compose.yaml 和环境变量示例。Loci Server 镜像已包含抓取动态文档所需的浏览器运行时,不需要额外部署浏览器容器。服务器需要安装 Git、Docker 和 Docker Compose。

克隆仓库后,复制环境变量示例:

cp .env.example .env

至少需要在 .env 中设置以下值:

环境变量用途
LOCI_ADMIN_PASSWORDAdmin 登录密码,应替换为足够长的随机值。
LOCI_ADMIN_USERNAMEAdmin 登录账号,默认是 admin。
LOCI_SERVER_IMAGE后端镜像,默认使用 GHCR 上的 latest。
LOCI_SERVER_PORT发布到宿主机的端口,默认是 3000。

保存配置后启动服务:

docker compose pull
docker compose up -d

确认健康检查可以访问:

curl http://127.0.0.1:3000/health

生产环境应通过 HTTPS 反向代理暴露 Loci Server,并保留 Compose 创建的 loci-data 数据卷。当前版本按单实例运行。

连接部署后的 Server

正式版 CLI 默认连接 https://loci.xiaowo.live。管理官方 Server 时可以直接运行检查;管理自行部署的 Server 时,先改为部署后的 HTTPS 地址:

loci config set server-url https://your-loci.example.com
loci doctor

loci doctor 会检查 /health 是否可以访问。其他用户也需要设置同一个地址,之后便可通过 loci cloud list 浏览已发布的文档库。

通过 Web 管理

先按上面的方式配置目标 Server,再打开本机 Web:

loci ui

从顶栏工作区切换器进入“Server 管理”,使用 Server 管理员账号登录。未登录或会话到期时会进入不带本地工作区侧栏和顶栏的独立登录页;从 Admin 子页面进入登录后,成功登录会返回原页面。登录后顶栏右侧会持续显示管理员用户名。侧边栏按“概览”“内容管理”“任务与策略”“审计与诊断”分组,提供 Server 概览、文档库、公开目录预览、同步任务、抓取策略、管理操作记录和浏览器诊断。公开目录预览只展示访问者可见的已发布快照,不提供本地拉取或删除动作。

Web 与本地文档库共用来源类型、名称、起始 URL、收录范围、页面上限和更新计划等基础字段,只在发布状态、批量同步和远程任务等 Server 特有位置保留差异。只有持有有效 Server 管理会话的用户,才会在“本地文档库”看到某一包含正文的库的“发布”操作;未登录、会话加载中、请求失败或会话到期时不会显示。登录后页面会并列显示本地来源、目标 Server、创建或覆盖方式及影响范围,确认后可直接查看目标 Server 文档库。Server 文档库页也提供“从本地发布”入口,返回选择来源。新建时根据 URL 自动识别普通站点或 GitHub 仓库并生成名称;自定义 Cron 会预览最近两次运行时间;更换已有文档库的起始 URL 会立即清空现有内容,收窄范围会立即删除范围外正文,Web 会在保存前展示危险确认。Web 支持查看、创建、编辑和删除 Server 文档库,单个、所选或全部同步,以及查看和取消同步任务;任务按 hostname 卡片分组并提供独立滚动区域、错误悬停详情和二次确认。普通工作区通过一条本机 SSE 接收远端 revision 更新;远端 Bearer Token 只保存在本机 Runtime 内存,不会暴露给浏览器,因此其他 CLI 或 Server 请求提交的修改也会自动出现。同一文档库的重复请求仍由 Server 复用已有活动任务,同一 hostname 串行而不同 hostname 可并发。

“抓取策略”页面只提供 Server 最大并行任务数。页面并发、重试、超时和浏览器资源回收由共享执行层管理,不提供域名覆盖。同一 hostname 任务串行仍是安全约束。降低任务容量不会中止运行中的任务;发生并发管理员修改冲突时,Web 会刷新最新配置并要求重新提交。

管理员登录后还可以打开“Server 浏览器”页面,查看远端提供方是镜像内 Chromium、Browserless 还是未配置,并执行真实启动或连接检测。页面只展示脱敏后的 Browserless 地址,不返回令牌。Server 侧浏览器由部署配置负责:本地 Chromium 需要重新构建镜像,Browserless 需要修改环境变量并重新部署;Web 不在运行中的容器内安装或卸载浏览器。

Web 新建 Server 文档库后会立即提交首次同步。创建成功但同步任务提交失败时,文档库配置仍会保留并显示警告,管理员可以修正后重试;首次任务被取消且文档库仍为空时会同时删库。只有成功抓到至少一个页面后,文档库才会出现在公开目录中。

Server 会持久记录认证后成功的管理写请求,Web 的“管理操作记录”可以分页查看管理员、请求方法、管理路径、响应状态和时间。请求正文、密码和 Token 不进入审计记录;查看页面等 GET 请求也不会产生新记录。

登录密码只用于一次本机请求。Server 返回的 Admin Token 由 loci ui 所在 Runtime 保存在内存中,不返回浏览器、不写入 SQLite;关闭该命令后需要重新登录。Web 与 CLI 复用同一个远程 Admin 客户端和 Server API,CLI 更适合终端交互与自动化。

使用 Admin 会话

运行以下命令进入交互式管理会话:

loci admin

CLI 会读取管理员账号和隐藏输入的密码。登录后可以执行以下操作:

  • 查看 Server 文档库;
  • 创建文档库;
  • 修改文档库基础信息;
  • 单独设置自动更新计划;
  • 删除文档库及其已发布快照;
  • 多选或全选文档库同步并查看聚合进度。
  • 查看同步任务的页面进度、失败页和错误,并选择取消活动任务。

创建文档库时只询问第一个公开文档页面 URL,自动生成名称,默认整站范围、1,000 页和手动更新。名称、范围与页面上限可在创建后修改,计划单独设置。

CLI 只记住管理员账号和同步选择,不复用上次创建的范围、容量或计划。密码、Token、删除目标和危险确认不会保存。

修改基础信息和设置自动更新计划是两个独立操作,不需要为了调整计划重新填写名称和 URL。自定义 Cron 时,CLI 会在输入框底部实时展示最近两次预计执行时间,并在当前字段内提示格式错误。

管理员密码和登录 Token 只保存在当前 CLI 进程的内存中。退出 Admin 会话后,CLI 会注销 Token,下一次管理时需要重新登录。

CLI 新建 Server 文档库只保存抓取配置,不会发布空快照。创建后可在管理会话中选择“同步 Server 文档库”,使用已记住的勾选提交首次同步;只有成功抓到至少一个页面后,文档库才会出现在公开目录中。Web 为交互效率会在创建后自动提交同一首次同步流程。

用脚本管理 Server

自动化任务通过环境变量提供凭据,避免密码进入 shell 历史。每个命令结束后都会注销临时 Token。

export LOCI_ADMIN_USERNAME=admin
export LOCI_ADMIN_PASSWORD='replace-with-secret'

loci admin libraries
loci admin create --url https://vueuse.org/guide/ --scope /guide --page-limit 2000 --schedule '0 2 * * *'
loci admin update vueuse --scope /guide
loci admin update vueuse --schedule off
loci admin sync --all --wait
loci admin jobs
loci admin pause <任务 ID> --yes
loci admin resume <任务 ID> --yes
loci admin stop <任务 ID> --yes
loci admin cancel <任务 ID> --yes
loci admin priority <任务 ID> 50 --yes
loci admin pause-all --hostname docs.example.com --yes
loci admin settings
loci admin settings-set --max-jobs 4
loci admin publish <本地文档库> --yes

--schedule off 关闭 Server 自动更新计划;旧脚本中的 manual 仍可作为兼容别名。admin libraries 显示发布状态、最近同步和错误;admin jobs 显示 hostname、页面进度、正文大小、耗时和失败原因。任务引用可以是完整 ID 或列表中的唯一短 ID;暂停与恢复复用原任务,结束保留部分正文和剩余检查点,取消丢弃本次内容。admin sync 可以接收多个名称、完整 ID 或唯一短 ID;使用 --all 提交全部文档库,使用 --wait 在当前终端等待聚合结果。同一文档库重复提交时,Loci 会复用已有任务并显示当前进度。

admin settings 查看 Server 任务容量,admin settings-set --max-jobs 4 修改最大并行任务数。页面执行参数由共享底层管理。admin publish 将所选本地文档库打包为经过校验的压缩二进制归档;省略 --target 创建新 Server 文档库,提供 --target 时只在明确确认后覆盖目标。归档只包含该库的公开元数据和正文,不上传本机设置、凭据或任务历史。 暂停的排队任务会释放执行名额,让其他文档库继续运行;恢复时复用原任务 ID 并重新入队。等待执行资格时也可以安全取消任务。

admin update 更换 URL 或收窄范围时,Server 会在保存事务中立即清空或裁剪正文,并同步更新已发布快照;正文清空后,该库从公开目录移除,旧快照不再可下载。未发布的文档库不会因修改配置自动发布。显式脚本参数表示调用方已确认影响。CLI 的 Server 地址遵循 LOCI_SERVER_URL 高于持久 server-url 的优先级。

删除命令在非交互环境中必须显式提供 --yes。

发布后的用户流程

Server 完成首次同步后,其他用户可以下载只读快照:

loci config set server-url https://your-loci.example.com
loci cloud list
loci cloud pull <文档库名称或 ID>

下载后的内容保存在用户本地,可以离线浏览和搜索。用户不能通过公开文档库接口修改 Server 上的文档源。

部署边界

  • 只添加公开且无需登录的文档页面,不要填写 Cookie、Token 或其他站点凭据。
  • Hash Router 文档站依赖 # 区分页面,当前不适合作为文档源。
  • 生产环境应通过防火墙或云网络策略,在每个实际发起目标连接的执行环境阻止内网和云元数据地址。默认本地 Chromium 需覆盖 Loci Server 容器;显式使用远程 Browserless 时也必须覆盖 Browserless 执行环境。

如果只需要使用别人已经发布的文档库,请返回云端文档库,无需阅读或执行本页的部署步骤。