后台服务与 Web UI
Loci 把 Web 会话和后台执行拆成两个独立进程角色:loci ui 只在当前终端提供 Web 静态资源与本机 API;无 HTTP 的 worker 负责抓取任务、定时计划和云端副本检查。两者可以同时运行,并复用同一份 SQLite 数据库、持久任务队列和跨进程锁。
普通后台同步会按需启动 worker,队列空闲后自动退出。只有定时抓取或云端每日同步需要用户级常驻 worker;常驻 worker 不监听 HTTP 端口。
打开 Web UI
命令会先打印普通随机回环地址,再默认尝试打开一次系统浏览器。HTTP 只监听 127.0.0.1,仅在 loci ui 运行期间存在,不开放局域网访问,也不执行抓取或定时调度。
关闭浏览器页面不会停止命令;在终端按 Ctrl+C,或向进程发送 SIGINT、SIGTERM,会关闭 HTTP。已经提交的后台任务不属于 Web 进程,会继续由 worker 执行。浏览器无法自动打开时,Loci 不会退出,可复制终端中已打印的地址手动访问。
只输出访问地址而不尝试自动打开浏览器:
Web UI 覆盖文档工作区、后台任务、公开云端目录、本机无头浏览器、Server 管理、Agent 全局接入、运行设置和备份恢复。“无头浏览器”页面可以查询、安装和卸载与 CLI 共用的本机 Chromium,并在运行期间显示进度;“Agent”页面可以检查、配置和移除当前用户的 MCP、全局 Skill 与 Rules。项目级 Skill 和服务治理继续使用 CLI。
文档阅读
进入文档库后按需读取目录与正文。目录搜索覆盖尚未展开的页面,并保留和展开匹配页面的路径;搜索或展开全部只获取目录元数据,不下载全部正文。
本地与云端阅读地址记录文档库和文章 ID,可以复制地址分享或刷新恢复。正文中的相对链接和图片按来源 URL 解析,正文链接在新标签页打开来源页面;访问外部来源仍需要网络。
阅读视图隐藏 YAML 头部和 MDX 展示包装,保留正文与代码示例;自定义标题锚点用于文内跳转,不显示为标题文字。Vue 等文档的提示容器以静态标题和正文展示。“复制 Markdown”仍返回原始正文。阅读器不执行源站 MDX 组件或脚本,不复现源站交互演示。
管理常驻 worker
使用默认数据目录时,start 会安装并启动当前用户的登录自启动 worker。loci schedule set、loci cloud pull --auto-sync、loci cloud auto-sync ... --on 以及 Web UI 中开启的持久能力,都会在保存时立即确保它可用,不需要等待 Web 会话退出。
stop 停止当前登录会话中的常驻 worker,但保留登录自启动定义,下次登录仍会自动重启;disable 在停止的基础上同时移除登录自启动,直到手动执行 start 才会恢复。已保存的计划和自动同步开关在 stop 或 disable 后均继续保留,但停用期间不会执行。
设置 LOCI_DATA_DIR 后,自动启用持久能力不会改写唯一的用户级服务定义,而是为该目录启动当前登录会话中的独立 detached worker;它不保证进程退出、注销或机器重启后自动恢复。测试和临时环境可以接受这个边界。loci service start、stop、restart 和 disable 面向单个用户级服务定义,不提供多目录服务治理;不要用它们同时维护多个自定义目录。长期运行的自定义目录应由容器或系统进程管理器设置相同环境变量,并在前台托管 loci service run。
stop 停止当前登录会话中的常驻 worker,但保留登录自启动定义;disable 同时移除登录自启动。已保存的计划和自动同步开关仍会保留,但停用期间不会执行;再次开启持久能力会重新激活 worker。Agent 的 stdio MCP 和按需后台任务不依赖常驻 worker。
loci status 会区分常驻 worker、按需 worker、“无需运行”和“需要启动”;loci doctor 在持久能力缺少宿主时给出 loci service start 修复建议。自动激活失败时,启用计划或自动同步的操作不会保存新的启用状态。
loci service logs 默认显示每个后台日志文件最近 50 行;--lines <number> 调整行数,--follow 持续输出新增内容并在 Ctrl+C 后退出。
容器、临时数据目录或调试环境可以在前台运行同一种无 HTTP worker:
任务与计划语义
- CLI、Web、stdio MCP、按需 worker 和常驻 worker 共用同一个 SQLite 任务队列。
- 同一来源同时触发只保留一个活动任务并复用进度;同一 hostname 的不同文档库按优先级串行,不同 hostname 可以并行。
- Web 的“后台任务”按 hostname 分组,支持筛选、全局或域名级暂停/恢复,以及单任务暂停、恢复、结束、取消和优先级调整。结束会保留本次已抓取正文和剩余检查点;取消会停止后续抓取并清除检查点,已经实时写入的成功页面继续保留,新建空文档库的首次任务被取消时会同时删库。
- 页面并发、重试和超时统一由共享执行层管理;同一 hostname 的后台任务仍串行执行。
- 域名概览与详情区分运行、暂停、异常、部分结束和完成;暂停或部分结束不会显示为成功完成。任务完成率表示已完整完成的任务占比,域名抓取进度仅汇总当前活动或暂停任务,历史任务不计入本次百分比。
- Web 普通工作区只建立一条回环 SSE。CLI、MCP 或 worker 修改来源、文档、任务、设置或操作日志后,Runtime 通过持久 revision 只失效相关页面数据;该监视器只在有浏览器订阅时运行,文档更新会同时刷新列表、当前正文和 URL 树。退出
loci ui不取消已提交任务。 - 按需 worker 通过跨进程锁 single-flight:并发启动只会有一个进程认领队列,空闲后自动退出。
- 常驻 worker 与 Web 可以同时运行;同一数据目录只允许一个 worker 认领任务。
- 机器休眠、关机或常驻 worker 停用期间不能按时执行。恢复后,同一计划错过的多个时间点合并为一次补跑。
- 后台
auto在缺少 Chromium 时直接使用 HTTP;显式browser抓取需要先运行loci browser install。
Web UI 不要求浏览器会话认证。包括 Agent 文件写入在内的业务 API 只绑定 127.0.0.1 并校验本机 Host;写请求额外校验 Origin。Server Admin 密码只随一次登录请求进入本机 Runtime,换取的远程 Token 只保存在该 Runtime 的内存中,不会返回浏览器或写入 SQLite;结束 loci ui 后该管理会话随之失效。