#Admin：部署与管理 Server

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

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

#部署 Loci Server

仓库根目录提供了生产环境使用的 compose.yaml 和环境变量示例。GHCR 发布的 Loci Server 镜像内置轻量的 Chromium headless shell，只执行 JavaScript、生成 DOM 并把 HTML 交给现有 Markdown 转换链路，不需要额外启动 Browserless 容器。服务器需要安装 Git、Docker 和 Docker Compose。

克隆仓库后，复制环境变量示例：

cp .env.example .env

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

保存配置后启动服务：

docker compose pull
docker compose up -d

确认健康检查可以访问：

curl http://127.0.0.1:3000/health

生产环境应通过 HTTPS 反向代理暴露 Loci Server，并保留 Compose 创建的 loci-data 数据卷。当前版本按单实例运行，不要让多个 Server 实例同时写入同一份 SQLite 数据。

#连接部署后的 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 浏览已发布的文档库。

#使用 Admin 会话

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

loci admin

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

• 查看 Server 文档库；
• 创建文档库；
• 修改文档库基础信息；
• 单独设置自动更新计划；
• 删除文档库及其已发布快照；
• 多选或全选文档库同步并查看聚合进度。

创建文档库时，CLI 会先询问第一个公开文档页面 URL，并根据域名生成可编辑的名称默认值。随后可以选择收录整个站点或某级路径；页面上限默认是 1000；自动更新计划可以选择仅手动、常用预设或自定义五段 Linux Cron。

成功操作后的安全偏好会按 Server 地址分别保存：下次登录会填入上次账号，创建会复用页面上限、收录路径层级和更新计划，批量同步会预勾选上次成功选择。只有一个文档库时会默认勾选，直接回车即可提交；上次选择了全部文档库时仍保持“全部文档库”勾选。密码、Token、删除目标和危险确认始终不会保存。

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

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

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

#用脚本管理 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 sync --all --wait
loci admin jobs
loci admin cancel <任务 ID>

admin sync 可以接收多个名称、完整 ID 或唯一短 ID；使用 --all 提交全部文档库， 使用 --wait 在当前终端等待聚合结果。Server 最多同时运行 3 个文档库，其余任务排队。 同一文档库只保留一个活动任务；重复提交会返回已有任务及其当前进度，不会再启动一份抓取。 删除命令在非交互环境中必须显式提供 --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 headless shell 只在 Server 容器内部启动，不对公网暴露调试端口。
• Server 仍兼容远程 Browserless，但默认不需要额外的浏览器容器。

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