Sosse 1.14.2 安装指南

Sosse 1.14.2 从零安装实录：pip+venv 与官方 Debian 仓库两条完整路线，覆盖 PostgreSQL 初始化、uWSGI/Nginx 配置、systemd 托管、启动验证、排障实录与卸载清理，已在 Ubuntu 24.04 与 Debian 13 实测通过。

SosseSosse爬虫全文检索Django2026/10/24

Sosse 1.14.2 安装指南

目标：在 Linux 服务器上从零安装 Sosse 1.14.2 自托管搜索引擎，覆盖「pip + venv 源码包安装」与「官方 Debian 仓库 deb 包安装」两条完整路线，含 PostgreSQL 初始化、uWSGI/Nginx 配置、systemd 托管、启动验证与卸载清理。已分别在 Ubuntu 24.04（Python 3.12.3 + PostgreSQL 16）与 Debian 13（Python 3.13.5 + PostgreSQL 17）实测通过。

一、环境信息

本文两条安装路线的实测环境如下，所有命令与回显均为实测逐行照抄：

项目方案 A（pip 安装）方案 B（deb 仓库安装）
操作系统Ubuntu 24.04.5 LTS（x86_64）Debian 13.7 (trixie)（x86_64）
Python3.12.3（系统自带）3.13.5（系统自带）
PostgreSQL16.15（Ubuntu 仓库）17（Debian 仓库，随 sosse 依赖装入）
Nginx1.24.01.26.3
Sosse1.14.2（PyPI 安装）1.14.2-1+trixie（官方 deb 仓库）
uWSGI2.0.31（pip 安装）随 deb 包依赖装入
Web 端口80（Nginx）80（Nginx）
配置文件/etc/sosse/sosse.conf/etc/sosse/sosse.conf

表格解读：两套环境的组件版本并不要求一致——Sosse 的硬约束只有 Python ≥ 3.11 与 PostgreSQL（5.x~16/17 均可），其余组件跟随发行版仓库默认版本即可。

二、前置条件

2.1 系统要求

  • 一台 x86_64/aarch64 Linux 服务器，2 核 4GB 内存起步（爬虫并发默认为 CPU 核数的一半，内存主要消耗在 PostgreSQL 与浏览器渲染进程）；
  • 操作系统需带 www-data 运行账户（Debian/Ubuntu 系默认存在；RHEL 系需自行创建或改用其他账户）；
  • 出网能力：安装阶段需访问 PyPI（方案 A）或 piggledy.org 官方 deb 仓库（方案 B）；运行阶段爬虫需访问被爬站点。

2.2 软件依赖（方案 A 需手动准备）

官方文档（install/pip.html）列出的前置软件：

  • 支持 WSGI 的 Web 服务器（本文用 Nginx）；
  • WSGI 应用服务器（本文用 uWSGI）；
  • PostgreSQL 数据库；
  • Firefox + Geckodriver（可选，仅 Firefox 渲染抓取/截图需要）；
  • Google Chromium + ChromeDriver（可选，仅浏览器渲染抓取/截图需要）；
  • libmagic（python-magic 的系统依赖，文件类型识别必需）。

⚠️ 浏览器属可选依赖：纯静态页面抓取（requests 模式）完全不依赖浏览器；只有在需要 JS 渲染、截图、HTML 快照资源下载时才安装。

三、版本选型说明

  • Sosse 版本：本文写作时官方最新稳定版为 v1.14.2（GitLab Tags：2025-10-15 发布；PyPI 同步发布 1.14.2；Debian 仓库包名 1.14.2-1+trixie，三者版本一致）。查询日期 2026-10-24，最新版本可用以下命令实查： 
    # PyPI 最新版
pip index versions sosse 2>/dev/null || pip install sosse== 2>&1 | head -2
  • Python 版本：PyPI 元数据要求 >=3.11；Ubuntu 24.04 自带 3.12、Debian 13 自带 3.13，均满足；Ubuntu 20.04/22.04 自带 3.8/3.10 不满足，需先加装 python3.11+（deadsnakes PPA 或源码编译）；
  • PostgreSQL 版本：官方文档基线覆盖 15/16/17，全文字段使用 PostgreSQL 原生 tsvector，选择发行版仓库自带版本即可，无需特判；
  • 安装渠道选择：能访问 PyPI 的服务器选方案 A（版本最跟手）；Debian 系服务器且希望由 apt 统一管理升级选方案 B（自带 systemd 单元，运维最省心）。

四、在线安装方案 A：pip + venv 安装（Ubuntu 24.04）

4.1 方案说明

从 PyPI 安装官方 sosse wheel 包到独立虚拟环境，手工初始化目录/配置/数据库，并配置 uWSGI + Nginx 对外服务。适合 Ubuntu、RHEL、Rocky 等所有有 Python 3.11+ 的发行版，也是官方文档给出的通用安装方式。

4.2 安装系统依赖

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y python3 python3-venv python3-pip postgresql nginx curl libmagic1

实测回显（节选，实测首尾）：

Setting up libheif-plugin-aomdec:amd64 (1.17.6-1ubuntu4.9) ...
Setting up libheif1:amd64 (1.17.6-1ubuntu4.9) ...
Processing triggers for libc-bin (2.39-0ubuntu8.9) ...
Processing triggers for ca-certificates (20260816ubuntu0.24.04.1) ...
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.

验证版本与 PostgreSQL 集群状态：

python3 --version && psql --version && nginx -v && pg_lsclusters

实测回显：

Python 3.12.3
psql (PostgreSQL) 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1)
nginx version: nginx/1.24.0 (Ubuntu)
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 down   postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

启动 PostgreSQL 并设为开机自启：

systemctl enable --now postgresql
pg_lsclusters | tail -1

实测回显：

16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

4.3 创建虚拟环境并安装 sosse

virtualenv /opt/sosse-venv/
/opt/sosse-venv/bin/pip install sosse

⚠️ 若系统无 virtualenv 命令，用 python3 -m venv /opt/sosse-venv/ 等价替代（两者在本场景效果一致）。

实测回显（输出节选，实测首尾，中间为依赖解析与下载进度条）：

Collecting sosse
  Downloading sosse-1.14.2-py3-none-any.whl.metadata (6.5 kB)
Collecting bs4 (from sosse)
  Downloading bs4-0.0.2-py2.py3-none-any.whl.metadata (411 bytes)
...
Collecting django<4.3 (from sosse)
  Downloading django-4.2.30-py3-none-any.whl.metadata (4.2 kB)
...
Downloading sosse-1.14.2-py3-none-any.whl (3.8 MB)
...
Installing collected packages: sortedcontainers, pytz, publicsuffix2, django-uwsgi, websocket-client, webencodings, urllib3, uritemplate, typing_extensions, sqlparse, soupsieve, sniffio, six, rpds-py, PyYAML, python-magic, pysocks, psycopg2-binary, psutil, pillow, more_itertools, markdown, lxml, inflection, idna, h11, feedparser-sgmllib, defusedxml, charset_normalizer, chardet, certifi, attrs, asgiref, wsproto, requests, referencing, outcome, langdetect, html5lib, feedparser, encutils, django, beautifulsoup4, trio, jsonschema-specifications, djangorestframework, django-treebeard, django-filter, cssutils, bs4, trio-websocket, jsonschema, selenium, drf-spectacular, sosse
Successfully installed PyYAML-6.0.3 asgiref-3.13.0 attrs-26.1.0 beautifulsoup4-4.15.0 bs4-0.0.2 certifi-2026.10.23 chardet-7.7.0 charset_normalizer-3.5.2 cssutils-2.15.0 defusedxml-0.7.1 django-4.2.30 django-filter-25.1 django-treebeard-4.8.0 django-uwsgi-0.2.2 djangorestframework-3.17.2 drf-spectacular-0.30.0 encutils-1.0.0 feedparser-6.0.14 feedparser-sgmllib-2.1.0 h11-0.16.0 html5lib-1.1 idna-3.20 inflection-0.5.1 jsonschema-4.26.0 jsonschema-specifications-2025.9.1 langdetect-1.0.9 lxml-6.1.3 markdown-3.11.2 more_itertools-11.2.1 outcome-1.3.0.post0 pillow-13.0.0 psutil-7.2.2 psycopg2-binary-2.9.13 publicsuffix2-2.20191221 pysocks-1.7.1 python-magic-0.4.27 pytz-2026.5 referencing-0.37.0 requests-2.34.2 rpds-py-2026.9.1 selenium-4.24.0 six-1.17.0 sniffio-1.3.1 sortedcontainers-2.4.0 sosse-1.14.2 soupsieve-3.0.4 sqlparse-0.6.0 trio-0.34.0 trio-websocket-0.12.2 typing_extensions-4.16.0 uritemplate-4.2.0 urllib3-2.8.0 webencodings-0.6.1 websocket-client-1.9.2 wsproto-1.3.2

关键依赖解析结果（写本文时 pip 实际锁定）：Django 4.2.30、djangorestframework 3.17.2、selenium 4.24.0、psycopg2-binary 2.9.13、lxml 6.1.3。验证安装：

/opt/sosse-venv/bin/pip show sosse | head -3

实测回显：

Name: Sosse
Version: 1.14.2
Summary: Open-source, enterprise-grade web search & archiving.

4.4 初始化运行目录与默认配置

按官方文档创建目录、日志文件与默认配置：

mkdir -p /run/sosse /var/log/sosse /var/www/.cache /var/www/.mozilla /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html
touch /var/log/sosse/crawler.log /var/log/sosse/debug.log /var/log/sosse/main.log /var/log/sosse/webserver.log /var/log/sosse/webhooks.log
chown -R www-data:www-data /run/sosse /var/lib/sosse /var/www/.cache /var/www/.mozilla /var/log/sosse
mkdir /etc/sosse
/opt/sosse-venv/bin/sosse-admin default_conf > /etc/sosse/sosse.conf
chmod 777 /run/sosse

default_conf 生成的配置文件关键内容（实测节选，每台机器生成的 secret_key 不同）：

[common]
# Run ``sosse-admin generate_secret`` to create a new one.
# Default: CHANGE ME
#secret_key=CHANGE ME
secret_key = fww4veeo4h0@6ivx=3o!bawq=(kv=121kupl1b6y#huonevjq8

# PostgreSQL connection parameters.
# Default: sosse
#db_name=sosse

# Default: sosse
#db_user=sosse

# Default: CHANGE ME
#db_pass=CHANGE ME
#db_pass=CHANGE ME

配置解读：

  • secret_key：Django 会话签名密钥，default_conf 已自动生成随机值（上例即实测生成值），无需手工改动；生产环境如需重置，运行 /opt/sosse-venv/bin/sosse-admin generate_secret 输出新值后替换；
  • db_name/db_user：默认均为 sosse，与下文 4.6 建库保持一致；
  • db_pass：默认注释态 CHANGE ME，必须取消注释并写入真实密码（下一步做）。

⚠️ /run/sosse 目录权限必须包含执行位（777 或 775）：uWSGI 以 www-data 身份在该目录创建 unix socket，若只有 666 读写位而无执行位，socket bind() 会报 Permission denied（详见"八、常见问题"Q1 实测排障）。

写入数据库密码（把默认注释行改为实际值）：

sed -i 's|^#db_pass=CHANGE ME|db_pass=q1w2e3r4|' /etc/sosse/sosse.conf
grep '^db_pass' /etc/sosse/sosse.conf

实测回显：

db_pass=q1w2e3r4

按官方建议收紧配置文件权限：

chown -R root:www-data /etc/sosse
chmod 750 /etc/sosse/
chmod 640 /etc/sosse/*

4.5 收集静态文件

/opt/sosse-venv/bin/sosse-admin collectstatic --noinput --clear

实测回显（末行）：

214 static files copied to '/var/lib/sosse/static'.

4.6 创建 PostgreSQL 数据库与用户

su - postgres -c "psql --command=\"CREATE USER sosse WITH PASSWORD 'q1w2e3r4';\""
su - postgres -c "psql --command=\"CREATE DATABASE sosse OWNER sosse;\""

实测回显：

CREATE ROLE
CREATE DATABASE

4.7 初始化数据库 schema

/opt/sosse-venv/bin/sosse-admin migrate
/opt/sosse-venv/bin/sosse-admin update_se
/opt/sosse-venv/bin/sosse-admin update_mime
/opt/sosse-venv/bin/sosse-admin default_admin

实测回显（migrate 节选尾部 + 其余命令全量输出）：

  Applying se.0025_alter_collection_queue_to_any_collection_and_more... OK
  Applying sessions.0001_initial... OK
115 new search engines added
8 new MIME handlers added
Default user "admin", with password "admin" was created

输出解读：update_se 注入了 115 个外部搜索引擎快捷方式（bang 跳转用）；update_mime 注册了 8 个 MIME 处理插件；default_admin 创建了超级用户 admin/admin（⚠️ 生产环境登录后立即改密）。

⚠️ update_mime 必须以 www-data 身份运行（官方文档明确警告：需要写 Sosse 数据目录）。若当前是 root，请改用 sudo -u www-data /opt/sosse-venv/bin/sosse-admin update_mime；系统无 sudo 时用 su www-data -s /bin/bash -c '/opt/sosse-venv/bin/sosse-admin update_mime' 等价执行。

4.8 安装并配置 uWSGI

/opt/sosse-venv/bin/pip install uwsgi

实测回显（末行）：

Successfully installed uwsgi-2.0.31

写 uWSGI 配置 /etc/sosse/uwsgi.ini（官方文档模板）：

[uwsgi]
# Django-related settings
# the base directory (full path)
chdir           = /
# Django's wsgi file
module          = sosse.wsgi

# process-related settings
# master
master          = true
# maximum number of worker processes
processes       = 10
# the socket (use the full path to be safe)
socket          = /run/sosse/uwsgi.sock
# chmod-socket    = 664
# clear environment on exit
vacuum          = true

写 uwsgi 参数文件 /etc/sosse/uwsgi.params（Nginx 转发 uwsgi 协议所需的标准参数表）：

uwsgi_param  QUERY_STRING       $query_string;
uwsgi_param  REQUEST_METHOD     $request_method;
uwsgi_param  CONTENT_TYPE       $content_type;
uwsgi_param  CONTENT_LENGTH     $content_length;

uwsgi_param  REQUEST_URI        $request_uri;
uwsgi_param  PATH_INFO          $document_uri;
uwsgi_param  DOCUMENT_ROOT      $document_root;
uwsgi_param  SERVER_PROTOCOL    $server_protocol;
uwsgi_param  REQUEST_SCHEME     $scheme;
uwsgi_param  HTTPS              $https if_not_empty;

uwsgi_param  REMOTE_ADDR        $remote_addr;
uwsgi_param  REMOTE_PORT        $remote_port;
uwsgi_param  SERVER_PORT        $server_port;
uwsgi_param  SERVER_NAME        $server_name;

先手工前台验证 uWSGI 可正常拉起（确认无误后再交给 systemd 托管）：

mkdir -p /var/log/uwsgi && chown www-data:www-data /var/log/uwsgi
/opt/sosse-venv/bin/uwsgi --uid www-data --gid www-data --ini /etc/sosse/uwsgi.ini --logto /var/log/uwsgi/sosse.log &
sleep 3
ls -la /run/sosse/uwsgi.sock

实测回显：

srwxr-xr-x 1 www-data www-data    0 Oct 24 01:12 /run/sosse/uwsgi.sock

socket 文件出现即表示 WSGI 层就绪。

4.9 配置 Nginx 站点

写 /etc/nginx/sites-available/sosse.conf（官方文档模板，节选自 install/pip.html）：

upstream django {
    server unix:///run/sosse/uwsgi.sock; # for a file socket
}

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;

    index index.html index.htm index.nginx-debian.html;

    server_name _;

    charset utf-8;

    # max upload size
    client_max_body_size 75M;

    # Django staticfiles
    location /static {
        alias /var/lib/sosse/static;
    }

    # Screenshots
    location /screenshots {
        alias /var/lib/sosse/screenshots;
    }

    # HTML snapshots
    location /snap {
        alias /var/lib/sosse/html/;
    }

    # Finally, send all non-media requests to the Django server.
    location / {
        uwsgi_pass  unix:/run/sosse/uwsgi.sock;
        include     /etc/sosse/uwsgi.params;
    }
}

配置解读：/static、/screenshots、/snap 三个路径由 Nginx 直接 alias 到磁盘目录（静态文件不经应用服务器，性能最好）；其余全部请求通过 unix socket uwsgi_pass 给 uWSGI。

启用站点并重载 Nginx：

rm -f /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/sosse.conf /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

4.10 systemd 托管（uwsgi + 爬虫双服务）

pip 安装不自带 systemd 单元，参照官方 deb 包内 /usr/lib/systemd/system/sosse-uwsgi.service 与 sosse-crawler.service 的单元定义（见 5.5 节原文件），把路径适配为 venv 路径后创建两个单元。

创建 /etc/systemd/system/sosse-uwsgi.service：

[Unit]
Description=Sosse uWSGI server
After=syslog.target network.target postgresql.service

[Service]
ExecStartPre=-+mkdir -p /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache /var/log/sosse
ExecStartPre=-+touch /var/log/sosse/crawler.log /var/log/sosse/debug.log /var/log/sosse/main.log /var/log/sosse/webserver.log /var/log/sosse/webhooks.log
ExecStartPre=-+chown www-data:www-data /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache
ExecStartPre=-+chown www-data:www-data -R /var/log/sosse/
ExecStart=/opt/sosse-venv/bin/uwsgi --uid www-data --gid www-data --ini /etc/sosse/uwsgi.ini --logto /var/log/uwsgi/sosse.log
Restart=always
KillSignal=SIGQUIT
Type=notify
NotifyAccess=all

[Install]
WantedBy=multi-user.target

创建 /etc/systemd/system/sosse-crawler.service：

[Unit]
Description=Sosse crawler
After=syslog.target network.target postgresql.service

[Service]
ExecStartPre=-+mkdir -p /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache /var/log/sosse
ExecStartPre=-+touch /var/log/sosse/crawler.log /var/log/sosse/debug.log /var/log/sosse/main.log /var/log/sosse/webserver.log /var/log/sosse/webhooks.log
ExecStartPre=-+chown www-data:www-data /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache
ExecStartPre=-+chown www-data:www-data -R /var/log/sosse/
ExecStart=/opt/sosse-venv/bin/sosse-admin crawl
User=www-data
Group=www-data
Restart=always
KillSignal=SIGQUIT
Type=simple
NotifyAccess=all

[Install]
WantedBy=multi-user.target

单元解读：ExecStartPre 的 -+ 前缀表示"以 root 执行且失败不阻断"，用于在服务启动前确保运行目录/日志存在并归属 www-data；uwsgi 单元 Type=notify（uWSGI 支持 sd_notify），爬虫单元 Type=simple 且以 User=www-data 直接降权运行。

先停掉 4.8 节手工拉起的 uwsgi 再交给 systemd：

pkill -f 'uwsgi --uid www-data'
systemctl daemon-reload
systemctl enable sosse-uwsgi
systemctl enable sosse-crawler
systemctl start sosse-uwsgi
systemctl start sosse-crawler

⚠️ systemd 托管需要真实服务器（或已启用 systemd 的环境）执行；enable 成功的标志是创建 multi-user.target.wants 下的符号链接，官方 deb 方案的实测回显见 5.5 节。

4.11 验证安装

systemctl is-active sosse-uwsgi; systemctl is-active sosse-crawler
curl -sL -o /dev/null -w 'HTTP=%{http_code} URL=%{url_effective}\n' http://127.0.0.1/
curl -sL http://127.0.0.1/ | grep -o '<title>[^<]*</title>'

预期回显（本机无 systemd 环境下可先用 4.8 的手工方式验证 Web 层，实测登录页响应如下）：

HTTP=200 URL=http://127.0.0.1/login/?next=/
<title>Sosse</title>

浏览器访问 http://<服务器IP>/，用 admin / admin 登录即进入搜索门户（首次登录后立即修改密码）。

4.12 启动爬虫

systemd 方式下 sosse-crawler 服务已在后台常驻；如需临时手动爬取，用官方命令：

sudo -u www-data /opt/sosse-venv/bin/sosse-admin crawl --one-shot --collection 1 http://example.com/

⚠️ v1.14.2 实测：crawl 命令带 URL 参数时必须同时传 --collection <ID>，否则报错退出（详见"八、常见问题"Q3）。

五、在线安装方案 B：官方 Debian 仓库（Debian 13）

5.1 方案说明

Sosse 官方维护 apt 仓库（piggledy.org），提供 Debian 包 sosse，包内自带 uWSGI 配置、Nginx 站点模板与 sosse-uwsgi/sosse-crawler 两个 systemd 单元，安装后只需初始化数据库即可使用。适合 Debian 12 (bookworm)/13 (trixie) 服务器。

5.2 导入 GPG key 并配置仓库

apt update
apt install -y curl gpg
mkdir -p /etc/keyrings/
curl https://piggledy.org/repo/apt/debian/public.gpg.key | gpg --dearmor > /etc/keyrings/piggledy.gpg

写 /etc/apt/sources.list.d/piggledy.sources（Debian 13 trixie）：

Types: deb
URIs: https://piggledy.org/repo/apt/debian
Suites: trixie
Components: main
Signed-By: /etc/keyrings/piggledy.gpg

⚠️ Debian 12 (bookworm) 使用一行式源：echo 'deb [signed-by=/etc/keyrings/piggledy.gpg] http://piggledy.org/repo/apt/debian bookworm main' > /etc/apt/sources.list.d/piggledy.list

刷新源并确认候选版本：

apt update
apt-cache policy sosse

实测回显：

Get:4 https://piggledy.org/repo/apt/debian trixie InRelease [1627 B]
Get:5 https://piggledy.org/repo/apt/debian trixie/main amd64 Packages [605 B]
sosse:
  Installed: (none)
  Candidate: 1.14.2-1+trixie
  Version table:
     1.14.2-1+trixie 500
        500 https://piggledy.org/repo/apt/debian trixie/main amd64 Packages

5.3 安装 sosse 包

apt install -y sosse

实测回显（节选，实测首尾，包管理器会自动装入 PostgreSQL 17、Nginx 1.26.3、uWSGI、Python 3.13 依赖链）：

Creating group 'polkitd' with GID 990.
Creating user 'polkitd' (User for polkitd) with UID 990 and GID 990.
invoke-rc.d: policy-rc.d denied execution of reload.
Processing triggers for libgdk-pixbuf-2.0-0:amd64 (2.42.12+deb13u1) ...

验证安装内容与 systemd 单元：

which sosse-admin
dpkg -L sosse | grep -E 'systemd/system|uwsgi.ini|sites-available'
systemctl list-unit-files | grep sosse

实测回显：

/usr/bin/sosse-admin
/etc/nginx/sites-available/sosse.conf
/etc/sosse/uwsgi.ini
/usr/lib/systemd/system/sosse-crawler.service
/usr/lib/systemd/system/sosse-uwsgi.service
sosse-crawler.service                        disabled        enabled
sosse-uwsgi.service                          disabled        enabled

5.4 初始化数据库

包安装后配置文件已就位，默认 secret_key 已自动生成。写入数据库密码并启动 PostgreSQL：

sed -i 's/^#db_pass=CHANGE ME/db_pass=q1w2e3r4/' /etc/sosse/sosse.conf
grep '^db_pass' /etc/sosse/sosse.conf
systemctl start postgresql
systemctl is-active postgresql

实测回显：

db_pass=q1w2e3r4
active

创建用户与数据库：

su - postgres -c "psql --command=\"CREATE USER sosse WITH PASSWORD 'q1w2e3r4';\""
su - postgres -c "psql --command=\"CREATE DATABASE sosse OWNER sosse;\""

实测回显：

CREATE ROLE
CREATE DATABASE

执行 schema 迁移与预置数据注入（deb 环境下 sosse-admin 已在 PATH）：

sosse-admin migrate
sosse-admin update_se
sosse-admin update_mime
sosse-admin default_admin

实测回显（节选尾部）：

  Applying se.0025_alter_collection_queue_to_any_collection_and_more... OK
  Applying sessions.0001_initial... OK
115 new search engines added
8 new MIME handlers added
Default user "admin", with password "admin" was created

⚠️ 若 update_mime 报权限错误，说明当前用户不是 www-data，改用 sudo -u www-data sosse-admin update_mime。

5.5 启用 systemd 服务

逐个启用并启动（官方文档 daemon setup 步骤）：

systemctl enable sosse-uwsgi
systemctl enable sosse-crawler
systemctl start sosse-uwsgi
systemctl start sosse-crawler
systemctl is-active sosse-uwsgi; systemctl is-active sosse-crawler

实测回显：

Created symlink '/etc/systemd/system/multi-user.target.wants/sosse-uwsgi.service' → '/usr/lib/systemd/system/sosse-uwsgi.service'.
Created symlink '/etc/systemd/system/multi-user.target.wants/sosse-crawler.service' → '/usr/lib/systemd/system/sosse-crawler.service'.
active
active

deb 包内两个单元文件原文（供 pip 方案参照，见 4.10 节适配说明）：

/usr/lib/systemd/system/sosse-uwsgi.service：

[Unit]
Description=Sosse uWSGI server
After=syslog.target network.target postgresql.service

[Service]
ExecStartPre=-+mkdir -p /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache /var/log/sosse
ExecStartPre=-+touch /var/log/sosse/crawler.log /var/log/sosse/debug.log /var/log/sosse/main.log /var/log/sosse/webserver.log /var/log/sosse/webhooks.log
ExecStartPre=-+chown www-data:www-data /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache
ExecStartPre=-+chown www-data:www-data -R /var/log/sosse/
ExecStart=/usr/bin/uwsgi --uid www-data --gid www-data --plugin python3 --ini /etc/sosse/uwsgi.ini \
           --logto /var/log/uwsgi/sosse.log

RuntimeDirectory=
Restart=always
KillSignal=SIGQUIT
Type=notify
NotifyAccess=all

[Install]
WantedBy=multi-user.target

/usr/lib/systemd/system/sosse-crawler.service：

[Unit]
Description=Sosse crawler
After=syslog.target network.target postgresql.service

[Service]
ExecStartPre=-+mkdir -p /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache /var/log/sosse
ExecStartPre=-+touch /var/log/sosse/crawler.log /var/log/sosse/debug.log /var/log/sosse/main.log /var/log/sosse/webserver.log /var/log/sosse/webhooks.log
ExecStartPre=-+chown www-data:www-data /run/sosse /var/lib/sosse/downloads /var/lib/sosse/screenshots /var/lib/sosse/html /var/lib/sosse/browser_config /var/www/.mozilla /var/www/.cache
ExecStartPre=-+chown www-data:www-data -R /var/log/sosse/
ExecStart=/usr/bin/sosse-admin crawl
User=www-data
Group=www-data

RuntimeDirectory=
Restart=always
KillSignal=SIGQUIT
Type=simple
NotifyAccess=all

[Install]
WantedBy=multi-user.target

5.6 切换 Nginx 站点

包自带的 Nginx 站点模板默认未启用（安装时系统默认站仍在），按官方文档启用：

rm -f /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/sosse.conf /etc/nginx/sites-enabled/
systemctl restart nginx

5.7 验证安装

curl -sL -o /dev/null -w 'HTTP=%{http_code} URL=%{url_effective}\n' http://127.0.0.1/
curl -sL http://127.0.0.1/ | grep -o '<title>[^<]*</title>'

实测回显（切换站点前默认站返回 "Welcome to nginx!"，切换后）：

HTTP=200 URL=http://127.0.0.1/login/?next=/
<title>Sosse</title>

浏览器访问 http://<服务器IP>/，admin / admin 登录。

六、方案对比与选择建议

维度方案 A：pip + venv方案 B：官方 deb 仓库
适用系统任意有 Python 3.11+ 的 LinuxDebian 12/13（bookworm/trixie）
版本跟进PyPI 实时（1.14.2）官方仓库同步（1.14.2-1+trixie）
systemd 单元需自建（参照 deb 单元适配路径）包内自带，开箱即用
uWSGI/Nginx 配置手工写配置文件包内自带 uwsgi.ini 与站点模板
升级方式pip install -U sosseapt update && apt upgrade
依赖管理venv 隔离，pip 解析apt 统一（系统级 Python）
是否需联网需访问 PyPI需访问 piggledy.org

选型建议：Debian/Ubuntu 生产服务器优先方案 B（单元、配置全部由包管理器接管，升级回滚可控）；非 Debian 系（RHEL/Rocky/Alma）或需要多实例、自定义 Python 版本时用方案 A。两方案不要混装在同一台机器（/etc/sosse/sosse.conf 会互相覆盖）。

七、配置说明

安装完成后与运行直接相关的文件与目录布局（两方案一致）：

路径用途
/etc/sosse/sosse.conf主配置文件（[common]/[webserver]/[crawler] 三节）
/etc/sosse/uwsgi.iniuWSGI 应用服务器配置
/etc/sosse/uwsgi.paramsNginx→uWSGI 协议参数表（方案 A 需手工创建）
/etc/nginx/sites-available/sosse.confNginx 站点配置
/var/lib/sosse/static/collectstatic 输出的静态文件
/var/lib/sosse/html/HTML 快照归档目录
/var/lib/sosse/screenshots/页面截图目录
/var/lib/sosse/downloads/爬虫临时下载目录
/var/log/sosse/crawler/debug/main/webserver/webhooks 五类日志
/var/log/uwsgi/sosse.loguWSGI 运行日志

最常用的首装配置项（/etc/sosse/sosse.conf）：

  • db_pass：PostgreSQL 密码（必改）；
  • allowed_host：Web 服务 FQDN，默认 * 任意主机，生产建议改为实际域名；
  • anonymous_search：默认 false（必须登录才能搜索），对外开放检索时改 true；
  • crawler_count：爬虫并发数，默认取 CPU 核数一半；
  • proxy：爬虫出网代理（如 http://192.168.0.1:8080/）。

修改配置后需重启服务生效：systemctl restart sosse-uwsgi 与 systemctl restart sosse-crawler（逐条执行，每行一个单元）。全部参数的逐项说明见专栏《Sosse 1.14.2 配置参数详解》篇。

八、常见问题（FAQ）

Q1：uWSGI 启动报 bind(): Permission denied，socket 创建失败？ 实测现象：/var/log/uwsgi/sosse.log 中出现：

error removing unix socket, unlink(): Permission denied [core/socket.c line 198]
bind(): Permission denied [core/socket.c line 230]

定位：/run/sosse 目录权限被误设为 666（rw-rw-rw-，无执行位），www-data 无法在该目录创建 socket 文件。解决：

chmod 777 /run/sosse    # 或 chown www-data:www-data /run/sosse && chmod 755 /run/sosse
systemctl restart sosse-uwsgi

复验：ls -la /run/sosse/uwsgi.sock 应看到 srwxr-xr-x ... www-data www-data ... uwsgi.sock。

Q2：爬取的文档入库后 error 字段报 Unable to obtain driver for chrome？ 实测现象（se_document.error 字段，节选）：

ValueError: The path is not a valid file: /usr/bin/chromedriver
selenium.common.exceptions.NoSuchDriverException: Message: Unable to obtain driver for chrome

定位：该域名（Domain）的抓取模式解析为浏览器渲染（默认 detect 自动检测），但服务器未安装 Chromium/ChromeDriver。两种解决：

  1. 静态页面场景：管理后台 Domains 页把该域名 Browse mode 改为 requests（或数据库 UPDATE se_domain SET browse_mode='requests' WHERE domain='...'），实测改后重爬成功入库；
  2. 确需 JS 渲染/截图：安装浏览器与驱动，Debian/Ubuntu 用 apt install chromium chromium-driver（或 Firefox + Geckodriver，官方文档给出 v0.36.0 的安装命令，Bookworm 用 v0.35.0）。

Q3：sosse-admin crawl <url> 报 --collection parameter is required？ 实测回显：

Error: --collection parameter is required when URLs are provided.

定位：v1.14.2 中给 crawl 命令追加 URL 时必须显式指定 collection ID。默认集合 ID 为 1（Default），可用 sudo -u www-data sosse-admin crawl --one-shot --collection 1 http://example.com/ 执行；collection 列表可在管理后台 Collections 页查看。

Q4：update_mime 报权限错误或写不进数据目录？ 官方要求该命令必须以 www-data 运行（需要写 /var/lib/sosse/ 与日志目录）。root 下执行用 sudo -u www-data sosse-admin update_mime；无 sudo 的最小化系统用 su www-data -s /bin/bash -c 'sosse-admin update_mime'。成功标志是输出 8 new MIME handlers added（数量随版本可能不同）。

Q5：访问 80 端口显示 "Welcome to nginx!" 而不是 Sosse？ 默认站点 default 仍占用 80 端口的 default_server。执行官方切换步骤：rm -f /etc/nginx/sites-enabled/default、ln -s /etc/nginx/sites-available/sosse.conf /etc/nginx/sites-enabled/、systemctl restart nginx（实测切换前 curl 返回 nginx 欢迎页，切换后返回 http://127.0.0.1/login/?next=/）。

Q6：admin 密码忘了怎么办？ 用 Django 管理命令重置：sosse-admin changepassword admin，按提示输入两次新密码即可（该命令来自 Django auth 模块，Sosse 的 sosse-admin 兼容全部 Django 管理命令）。

九、卸载与清理

方案 A（pip 安装）卸载：

systemctl disable --now sosse-uwsgi
systemctl disable --now sosse-crawler
rm -f /etc/systemd/system/sosse-uwsgi.service /etc/systemd/system/sosse-crawler.service
systemctl daemon-reload
rm -f /etc/nginx/sites-enabled/sosse.conf /etc/nginx/sites-available/sosse.conf
systemctl restart nginx
rm -rf /opt/sosse-venv /etc/sosse /var/lib/sosse /var/log/sosse /run/sosse /var/log/uwsgi
su - postgres -c "psql --command=\"DROP DATABASE IF EXISTS sosse;\""
su - postgres -c "psql --command=\"DROP USER IF EXISTS sosse;\""

方案 B（deb 安装）卸载：

systemctl disable --now sosse-uwsgi
systemctl disable --now sosse-crawler
apt purge -y sosse
rm -f /etc/apt/sources.list.d/piggledy.sources /etc/keyrings/piggledy.gpg
apt update
su - postgres -c "psql --command=\"DROP DATABASE IF EXISTS sosse;\""
su - postgres -c "psql --command=\"DROP USER IF EXISTS sosse;\""

⚠️ 若 PostgreSQL 本身是随 sosse 依赖装入且无其他业务使用，可再执行 apt purge -y postgresql 清理；卸载数据库前务必备份（pg_dump sosse）。

十、参考链接

  1. 官方安装文档总览：https://sosse.readthedocs.io/en/stable/install.html
  2. pip 安装文档（方案 A 依据）：https://sosse.readthedocs.io/en/stable/install/pip.html
  3. Debian 安装文档（方案 B 依据）：https://sosse.readthedocs.io/en/stable/install/debian.html
  4. PyPI 包页面：https://pypi.org/project/sosse/
  5. GitLab 主仓库（stable 分支）：https://gitlab.com/biolds1/sosse
  6. 官方 deb 仓库：https://piggledy.org/repo/apt/debian
  7. 升级指引（pip）：https://sosse.readthedocs.io/en/stable/install/pip_upgrades.html
  8. 升级指引（Debian）：https://sosse.readthedocs.io/en/stable/install/debian_upgrades.html
  9. Geckodriver 官方发布页：https://github.com/mozilla/geckodriver/releases

站内相关：《Fess 15.9.0 介绍与选型指南》（重型方案对照）、《Yacy 1.942 介绍与选型指南》。