Sosse 1.14.2 常用管理命令详解

目标：系统讲解 Sosse 1.14.2 的命令行工具 sosse-admin，覆盖爬取、索引维护、数据检索、备份导出、运维辅助五大场景的全部核心命令，并给出"本地测试站 → 爬取 → 入库 → 搜索验证"的完整实测链路回显与排障实录。全部命令已在 Ubuntu 24.04 + Sosse 1.14.2（pip 安装，venv 位于 /opt/sosse-venv）实测。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64，12 核），主机名 sosse-server
• Sosse：1.14.2（PyPI 安装，路径 /opt/sosse-venv/bin/sosse-admin）
• Python：3.12.3；PostgreSQL：16.15（127.0.0.1:5432，库/用户均为 sosse）；Nginx：1.24.0；uWSGI：2.0.31
• Web 服务：http://127.0.0.1/（Nginx 监听 80），管理员账号 admin/admin
• 实测测试站点：本地 HTTP 服务 127.0.0.1:8899 提供 3 个静态页面（index.html、page2.html、page3.html）
• 命令依据：sosse-admin help 实际输出 + 官方命令行文档 cli.html（https://sosse.readthedocs.io/en/stable/cli.html，查询日期 2026-10-24）双重核对

二、前置条件

• 已按《Sosse 1.14.2 安装指南》完成安装，sosse-admin 可执行（deb 安装在 PATH，pip 安装位于 <venv>/bin/sosse-admin）；
• PostgreSQL 已启动、配置文件 /etc/sosse/sosse.conf 中 db_pass 已正确设置；
• 爬虫相关命令（crawl/queue_status）建议以 www-data 身份运行（与爬虫服务进程一致，避免文件属主混乱）：sudo -u www-data sosse-admin <命令>；
• 检索验证需要至少完成一次爬取入库（本文实测链路在"五、场景实战"给出）。

三、命令族总览

sosse-admin 是 Django manage.py 的项目化包装：所有 Django 内置管理命令（migrate、collectstatic、createsuperuser、changepassword、dbshell、shell 等）与 Sosse 专属命令（crawl、queue_status、update_se 等）通过同一入口调用。运行 sosse-admin help 的实测回显（Sosse 专属命令段全量摘录）：

Type 'sosse-admin help' for help on specific commands.
...
[se]
    clear_html_archive
    convert_screens_to_jpeg
    crawl
    default_admin
    default_conf
    delete_documents
    dumpdata_sosse
    extract_doc
    generate_secret
    load_se
    queue_status
    update_mime
    update_se

命令族解读：[se] 是 Sosse 的 Django app 名，其下 13 个专属命令按用途分四类：

⚠️ 官方文档 cli.html 还提及 purge_cache 命令，但在 1.14.2 实测 sosse-admin help purge_cache 返回 Unknown command: 'purge_cache'（详见"七、常见问题"Q5 版本差异说明）。

四、命令参考

4.1 crawl — 爬虫启动与队列追加

爬虫的总入口：不带 URL 时作为常驻守护进程运行（systemd 的 sosse-crawler 服务即执行该命令）；带 URL 时把 URL 追加到队列后继续运行。--help 实测回显（全文）：

usage: sosse-admin crawl [-h] [--one-shot] [--collection COLLECTION]
                         [--all-url-params] [--no-html-snapshots]
                         [--no-screenshots] [--version] [-v {0,1,2,3}]
                         [--settings SETTINGS] [--pythonpath PYTHONPATH]
                         [--traceback] [--no-color] [--force-color]
                         [--skip-checks] [--noinput]
                         [urls ...]

positional arguments:
  urls                  Optional list of URLs to add to the crawler queue.

options:
  -h, --help            show this help message and exit
  --one-shot            Stops the crawler once the queue is empty.
  --collection COLLECTION
                        Use the given collection for the provided urls.
  --all-url-params      Crawl URLs with URL parameters.
  --no-html-snapshots   Disable HTML snapshots of the provided URLs.
  --no-screenshots      Disable screenshots of the provided URLs.
  --skip-checks         Skip system checks.
  --noinput, --no-input
                        Tells Django to NOT prompt the user for input of any
                        kind.

参数语义：

• --one-shot：队列清空后自动退出，适合定时任务（cron 定期爬取的推荐形态）；
• --collection <ID>：为本次追加的 URL 指定集合。⚠️ v1.14.2 实测：只要命令行上带了 URL，此参数就是必填，否则报 Error: --collection parameter is required when URLs are provided.；
• --all-url-params：允许带查询参数的 URL 入队（默认会忽略查询参数）；
• --no-html-snapshots/--no-screenshots：本次任务临时关闭快照/截图，不改集合配置。

4.2 queue_status — 队列与 worker 状态

实时输出待爬队列统计与 worker 进程状态，支持 --format json（机器可读）。实测回显（爬取空闲期）：

Crawlers status
Worker 0: idle
Worker 1: idle
Worker 2: idle
Worker 3: idle
Worker 4: idle
Worker 5: idle

Url queue
Processing: 0
New: 0
Recurring: 0
Total pending: 0

--format json 实测回显（节选，worker 详情含每 worker 处理量）：

{
  "timestamp": "2026-10-24T01:45:02.982860+00:00",
  "queue": {
    "processing": 0,
    "new": 0,
    "recurring": 0,
    "total_pending": 0
  },
  "workers": {
    "count": 6,
    "details": [
      {
        "worker_no": 0,
        "pid": null,
        "state": "exited",
        "doc_processed": 0,
        "current_url": null
      },
      {
        "worker_no": 1,
        "pid": null,
        "state": "exited",
        "doc_processed": 1,
        "current_url": null
      }
    ]
  }
}

输出解读：worker 总数 6 与默认 crawler_count（CPU 核数一半，本机 12 核）一致；爬取过程中 Processing/New 计数会实时跳动，适合作为监控采集源（json 格式直采）。

4.3 delete_documents — 批量删除已索引文档

按 URL 正则批量删除文档。--help 实测回显（节选）：

usage: sosse-admin delete_documents [-h] [--dry-run] [-i] [--exclude EXCLUDE] ... url regex

Mass delete documents.

positional arguments:
  url regex

options:
  -h, --help            show this help message and exit
  --dry-run             Prints the count of documents that would be deleted.
  -i, --ignore-case     Case insensitive matching.
  --exclude EXCLUDE     Regex pattern to exclude URLs from deletion.

实测：先 dry-run 预演，确认数量后再真删：

/opt/sosse-venv/bin/sosse-admin delete_documents --dry-run '127.0.0.1'
/opt/sosse-venv/bin/sosse-admin delete_documents '127.0.0.1'

实测回显（实测环境当时已索引 3 个页面）：

3 documents would be deleted
3 documents deleted

参数语义：url regex 为 Python 正则；--ignore-case 忽略大小写；--exclude 支持第二层正则反向豁免（如 delete_documents '.*example.*' --exclude 'cdn.example.*'）。⚠️ 删除不可恢复，生产操作务必先 --dry-run。

4.4 dumpdata_sosse / load_se — 数据备份与配置导入

• dumpdata_sosse：Django dumpdata 的项目定制版，把 Sosse 业务表导出为 JSON fixture。--help 摘要实测回显：

usage: sosse-admin dumpdata_sosse [-h] [--format FORMAT] [--indent INDENT]
                                  [--database DATABASE] [-e EXCLUDE]
                                  [--natural-foreign] [--natural-primary] [-a]
                                  [--pks PRIMARY_KEYS] [-o OUTPUT] ...

实测导出（限定单模型，输出体积更可控）：

/opt/sosse-venv/bin/sosse-admin dumpdata_sosse se.Collection -o /tmp/collections.json
wc -l /tmp/collections.json

实测回显：

919 /tmp/collections.json

• load_se：从 JSON fixture 导入外部搜索引擎快捷方式（与 update_se 不同：update_se 从包内置预置数据更新，load_se 从文件恢复）。

4.5 clear_html_archive / convert_screens_to_jpeg — 归档维护

clear_html_archive 清空 HTML 快照目录（--help 摘要实测回显）：

Clears archived HTML snapshots.

convert_screens_to_jpeg 把 PNG 截图批量转 JPEG 节省磁盘（--help 摘要实测回显）：

Convert all PNG screenshots to JPEG format.
options:
  --dry-run             Show what would be done without actually converting

⚠️ clear_html_archive 无 dry-run、不可恢复，执行前确认快照确无保留价值（或先备份 /var/lib/sosse/html/）。

4.6 update_se / update_mime / default_admin / default_conf / generate_secret — 初始化命令组

首次安装按序执行（实测回显见《Sosse 1.14.2 安装指南》4.7 节）：

/opt/sosse-venv/bin/sosse-admin migrate          # Django 库表迁移
/opt/sosse-venv/bin/sosse-admin update_se        # → 115 new search engines added
/opt/sosse-venv/bin/sosse-admin update_mime      # → 8 new MIME handlers added
/opt/sosse-venv/bin/sosse-admin default_admin    # → Default user "admin", with password "admin" was created

• update_se 可重复执行更新内置搜索引擎清单（升级后运行）；
• update_mime 必须 www-data 身份（需写数据目录）；
• default_conf 生成默认配置（重定向输出到 /etc/sosse/sosse.conf）；
• generate_secret 生成新密钥（实测输出形如 ludl)^aeowdgtiemw#9jk7jdx&qd$&2!14m&slkte5kf6!3-p)，轮换后需重启服务）。

4.7 Django 通用命令（高频子集）

表格解读：sosse-admin 对 Django 原生命令全兼容，Django 官方文档的管理命令章节均适用；唯一差别是无需指定 DJANGO_SETTINGS_MODULE（包内已封装）。

五、场景实战：从爬取到检索的完整链路

本章用本地测试站点（127.0.0.1:8899 的 3 个页面）走通"排队 → 爬取 → 入库 → 搜索"全链路，输出全部实测。

5.1 追加 URL 到队列

sudo -u www-data /opt/sosse-venv/bin/sosse-admin crawl --one-shot --collection 1 http://127.0.0.1:8899/index.html

实测（队列消费完成后）queue_status 回显：

Url queue
Processing: 0
New: 0
Recurring: 0
Total pending: 0

5.2 验证入库结果

查询 PostgreSQL 已索引文档（也可用管理后台 Documents 列表页查看）：

PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -U sosse -d sosse \
  -c "SELECT id, url, title, lang_iso_639_1, mimetype, error FROM se_document;"

实测回显：

 id |               url                |       title        | lang_iso_639_1 | mimetype  | error
----+----------------------------------+--------------------+----------------+-----------+-------
  1 | http://127.0.0.1:8899/index.html | Quzuo 测试站首页   | vi             | text/html |
  2 | http://127.0.0.1:8899/page2.html | Sosse 索引测试页   | de             | text/html |
  3 | http://127.0.0.1:8899/page3.html | 搜索引擎测试页     | vi             | text/html |
(3 rows)

输出解读：3 页全部入库、无 error；lang_iso_639_1 出现 vi/de 误检——爬虫对短文本的语言检测存在小样本偏差（自动回退与误检详见《Sosse 1.14.2 配置参数详解》5.9 节 fail_over_lang），不影响中文全文检索命中。

5.3 登录并搜索验证

用 curl 模拟浏览器登录后调用搜索接口（搜索入口即首页 /，参数 q）：

# 登录拿会话 Cookie（先取 CSRF token 再 POST 凭据）
CSRF=$(curl -s -c /tmp/cj.txt http://127.0.0.1/login/ | grep -o 'csrfmiddlewaretoken" value="[^"]*' | head -1 | cut -d'"' -f3)
curl -s -b /tmp/cj.txt -c /tmp/cj.txt -d "csrfmiddlewaretoken=$CSRF&username=admin&password=admin" \
     -H 'Referer: http://127.0.0.1/login/' -o /dev/null -w 'LOGIN=%{http_code}\n' http://127.0.0.1/login/

# 检索验证
curl -s -b /tmp/cj.txt 'http://127.0.0.1/?q=QuzuoTestKeywordAlpha' -o /tmp/s1.html -w 'ALPHA=%{http_code}\n'
curl -s -b /tmp/cj.txt 'http://127.0.0.1/?q=QuzuoTestKeywordGamma' -o /tmp/s2.html -w 'GAMMA=%{http_code}\n'
grep -oE '8899[^"<]*' /tmp/s1.html | head -2
grep -oE '8899[^"<]*' /tmp/s2.html | head -2

实测回显：

LOGIN=302
ALPHA=200
GAMMA=200
http://127.0.0.1:8899/index.html
http://127.0.0.1:8899/page3.html

输出解读：关键词 Alpha 命中 index.html（该词在首页）、Gamma 命中 page3.html，全文检索链路闭环。生产环境直接用浏览器操作即可，本节命令便于自动化冒烟测试。

5.4 一次性删除测试数据

/opt/sosse-venv/bin/sosse-admin delete_documents --dry-run '127.0.0.1'
/opt/sosse-venv/bin/sosse-admin delete_documents '127.0.0.1'

实测回显：

3 documents would be deleted
3 documents deleted

六、生产建议与最佳实践

1. 定时爬取：常驻 sosse-crawler 服务 + 集合的周期设置（Collections 管理页 Recrawl）即可满足常规增量；不建常驻进程时用 cron + crawl --one-shot（每行一条独立任务，注意 www-data 身份）；
2. 监控采集：queue_status --format json 输出结构稳定，直接对接监控系统抓队列积压（total_pending）与 worker 存活（state）；
3. 删除三步走：任何批量删除先 --dry-run 看计数，再缩小正则核对，最后真删；删除操作只清索引记录，不改已归档快照文件，确需彻底清理配合 clear_html_archive；
4. 升级流程：pip install -U sosse（或 apt 升级）→ sosse-admin migrate → sosse-admin update_se → sosse-admin update_mime（www-data）→ collectstatic --noinput --clear → 重启 uwsgi/crawler，逐条执行；
5. 备份节奏：pg_dump sosse 备库 + dumpdata_sosse 备配置双轨；快照/截图目录用文件级备份（rsync）；
6. 权限纪律：爬虫与 update_mime 用 www-data；dbshell/shell 等读操作用管理员即可；不要长期以 root 运行 crawl（浏览器进程会以 root 起 profile 目录，属主混乱难回收）。

七、常见问题（FAQ）

Q1：crawl <url> 报 --collection parameter is required when URLs are provided.？ v1.14.2 的命令行校验：命令行上给了 URL 就必须同时给 --collection <ID>。默认集合 ID 为 1（管理后台 Collections 页可查），补上参数即可。这是版本实测行为，官方 cli.html 的 usage 行未把该参数标注为必填。

Q2：爬取入库后 error 字段报 Unable to obtain driver for chrome？ 该域名自动检测为浏览器渲染模式但服务器没装浏览器驱动。静态站点在管理后台 Domains 页把 Browse mode 改为 requests（或数据库 UPDATE se_domain SET browse_mode='requests'），实测改后重爬 3 页全部入库；确需 JS 渲染则安装 Chromium + ChromeDriver（Debian/Ubuntu：apt install chromium chromium-driver）。

Q3：sosse-admin purge_cache 提示 Unknown command？ 1.14.2 已移除该命令（sosse-admin help 的 [se] 段无此命令，实测 Unknown command: 'purge_cache'）。官方文档 cli.html 仍提及它，属文档滞后。缓存清理替代：重启 sosse-crawler 服务；HTML 快照清理用 clear_html_archive。

Q4：update_mime 报权限错误？ 该命令写 /var/lib/sosse/ 与日志目录，必须 www-data 身份：sudo -u www-data sosse-admin update_mime；无 sudo 的最小化系统用 su www-data -s /bin/bash -c '<venv>/bin/sosse-admin update_mime'（实测同样输出 8 new MIME handlers added）。

Q5：crawl 爬不到任何页面，worker 很快 exited？ 排查顺序：① queue_status 看 Total pending 是否为 0（URL 没进队列，检查 --collection 是否指对集合）；② 看 /var/log/sosse/crawler.log 与 /var/log/uwsgi/sosse.log 有无异常栈；③ 查 se_document.error 字段定位单页错误（Q2 即典型案例）；④ 检查 Domain 的 robots.txt 策略是否拒绝、集合的认证/代理配置是否正确。

Q6：delete_documents 删除的文档还能恢复吗？ 不能。命令直接删除数据库记录（含全文向量），无软删除。误删后只能靠备份恢复（pg_dump/dumpdata_sosse）或重新爬取（URL 重新入队即可全量重建索引）。

八、参考链接

1. 官方命令行接口文档（本文命令依据）：https://sosse.readthedocs.io/en/stable/cli.html
2. 官方爬虫使用指南：https://sosse.readthedocs.io/en/stable/crawler.html
3. 管理界面文档（命令对应的 UI 操作）：https://sosse.readthedocs.io/en/stable/admin_ui.html
4. 伦理爬取指南（生产爬取规范）：https://sosse.readthedocs.io/en/stable/crawl_guidelines.html
5. Django 管理命令文档（通用命令上游参考）：https://docs.djangoproject.com/en/4.2/ref/django-admin/