Sosse 1.14.2 配置参数详解

目标：逐项讲清 Sosse 1.14.2 主配置文件 /etc/sosse/sosse.conf 全部参数的取值、默认值与改动影响，覆盖 [common]/[webserver]/[crawler] 三节共 60 余项配置，并给出环境变量覆盖机制的实测验证与三档生产配置模板。参数清单与默认值已在 Ubuntu 24.04（Sosse 1.14.2）实测核对。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• Sosse：1.14.2（pip 安装于 /opt/sosse-venv，安装过程见《Sosse 1.14.2 安装指南》）
• Python：3.12.3；PostgreSQL：16.15；Nginx：1.24.0；uWSGI：2.0.31
• 配置文件：/etc/sosse/sosse.conf（由 sosse-admin default_conf 生成）
• 参数依据：本文参数表逐项对照 sosse-admin default_conf 实际生成内容与官方文档 config_file.html（https://sosse.readthedocs.io/en/stable/config_file.html，查询日期 2026-10-24）双重核对

二、前置条件

• 已按《Sosse 1.14.2 安装指南》完成 Sosse 1.14.2 安装，sosse-admin 可用；
• 已知配置文件位置 /etc/sosse/sosse.conf，且对 root 或 www-data 有写权限；
• 理解配置改动需要重启服务才生效（Web 面 sosse-uwsgi、爬虫面 sosse-crawler 分别重启）。

三、参数查看与修改方式

3.1 查看当前生效配置

配置文件即"当前生效值"的唯一来源（环境变量覆盖项除外），直接阅读：

grep -vE '^\s*#|^\s*$' /etc/sosse/sosse.conf

实测回显（默认安装、已设置 db_pass 后的实际生效行）：

[common]
secret_key = fww4veeo4h0@6ivx=3o!bawq=(kv=121kupl1b6y#huonevjq8
db_pass=q1w2e3r4

[webserver]

[crawler]
#user_agent=Sosse

输出解读：default_conf 生成的文件里除 secret_key（自动生成）外全部为注释态默认值；db_pass 是唯一必须手工启用（去注释并赋值）的参数。

3.2 修改方式与生效条件

1. 编辑 /etc/sosse/sosse.conf（ini 格式，三节：[common]/[webserver]/[crawler]）；
2. 重启对应组件使改动生效：

   systemctl restart sosse-uwsgi
   systemctl restart sosse-crawler
   

3. 布尔值写法：true/false（小写）；留空参数写 参数名=（空值）。

3.3 环境变量覆盖机制（实测验证）

官方说明：任一配置项都可用 SOSSE_ 前缀的环境变量覆盖，例如 proxy 对应 SOSSE_PROXY，且环境变量优先级高于配置文件。

实测验证（用错误密码注入环境变量，观察 dbshell 连接结果）：

SOSSE_DB_PASS=wrongpass /opt/sosse-venv/bin/sosse-admin dbshell

实测回显（配置文件中 db_pass 实际正确，环境变量错误值覆盖后连接被拒）：

connection to server at "127.0.0.1", port 5432 failed: FATAL:  password authentication failed for user "sosse"
CommandError: "psql -U sosse -h 127.0.0.1 -p 5432 sosse" returned non-zero exit status 2.

取消环境变量后同命令连接成功（退出码 0），证明覆盖关系成立。该机制适合把密码等敏感值放在 systemd 的 Environment= 或容器/进程管理器环境中，而不是落在配置文件里。

3.4 生成新的 secret_key

/opt/sosse-venv/bin/sosse-admin generate_secret

实测回显（每次运行生成不同随机串）：

ludl)^aeowdgtiemw#9jk7jdx&qd$&2!14m&slkte5kf6!3-p)

四、参数总览

全部参数按所属节与作用域汇总（默认值取自 default_conf 生成文件，"留空"表示默认空值）：

表格解读：[common] 节两方组件共用（Web 与爬虫都要连库）；[webserver] 节只影响 uWSGI 承载的 Web 面；[crawler] 节只影响爬虫面——重启对应服务即可按需生效。

五、核心参数分类详解

5.1 数据库连接（[common]）

首次部署必改参数组。安装时只需启用 db_pass：

[common]
db_pass=q1w2e3r4

• db_name/db_user（默认 sosse/sosse）：与 CREATE DATABASE sosse OWNER sosse; 的建库语句对应；如改用其他库名/用户名，需同步修改建库 SQL 与本配置；
• db_host/db_port（默认 127.0.0.1:5432）：PostgreSQL 与 Sosse 分机部署时把 db_host 改为数据库服务器地址，并确认 pg_hba.conf 放行该来源；
• secret_key（自动生成）：Django 用它签名会话与 CSRF token。⚠️ 更换该值会使全部已登录会话失效；生产环境不要把示例文档中的密钥照抄进自己的配置。

验证数据库连通（改完 db_* 后执行）：

/opt/sosse-venv/bin/sosse-admin dbshell <<'EOF'
\q
EOF
echo EXIT=$?

实测回显（连接成功静默退出）：

EXIT=0

5.2 调试与错误展示（[common]）

• debug（默认 false）：Django DEBUG。开启后报错页会暴露源码路径与配置值，⚠️ 生产必须保持 false（官方文档同款警告）。

5.3 搜索行为（[webserver]）

• anonymous_search（默认 false）：false 时搜索前必须登录（实测安装后访问首页即 302 跳转 /login/?next=/，与该默认值一致）。对外开放检索入口时改 true；
• search_shortcut_char（默认 !）+ default_search_redirect：组合成 bang 跳转。例：default_search_redirect=google 后用户直接回车搜索会跳 Google；sosse_shortcut 可定义一个仍然搜 Sosse 自己索引的前缀（如 !s）；
• online_check_url（默认 https://google.com/）与 online_check_timeout（默认 1.0 秒）：Web 面用"能否在超时内访问该 URL"判定在线/离线，配合 online_search_redirect 实现"断网时搜内网、联网时搜外网"的切换。内网隔离环境把 online_check_url 指向内网探针地址即可；
• online_check_cache（默认 10）：每 10 次请求做一次真实在线判定，特殊值 once 只在首个请求判定一次，0 关闭缓存。官方注明缓存按 uWSGI worker 生命周期生效；
• default_page_size（默认 20）/max_page_size（默认 200）：结果分页的用户可调范围；
• search_strip：把出现在查询里的指定字符串剔除（如配置 - 后搜索 -django 等价于 django）；
• exclude_not_indexed/exclude_redirect（默认均 true）：把"已入队未索引完"与"纯重定向"页面挡在结果之外，避免搜到半成品；
• home_search_history_size（默认 3）：首页展示的最近搜索条数；
• browsable_home（默认 true）：首页展示集合入口文档（导航式首页）；
• links_no_referrer（默认 true）：点外链不带 referrer 头，避免向目标站泄露站内来源；
• links_new_tab（默认 false）：改 true 后外链在新标签页打开。

5.4 静态资源与快照路径（[webserver]）

四组 URL/目录配对（URL 前缀 ↔ 磁盘目录），需与 Nginx alias 配置一致：

• static_url=/static/ ↔ static_root=/var/lib/sosse/static/；
• screenshots_url=/screenshots/ ↔ screenshots_dir=/var/lib/sosse/screenshots/；
• html_snapshot_url=/snap/ ↔ html_snapshot_dir=/var/lib/sosse/html/。

⚠️ 官方 Danger 提示：html_snapshot_url 会被写死进已存的 HTML 快照内部链接——一旦修改，历史快照里的内链全部失效，需重爬才能修复。没有充分理由不要动它。 scripts_dir（默认 /var/lib/sosse/scripts/）：存放爬取处理脚本（MIME 插件可调用）。

5.5 本地化与时区（[webserver]）

• use_i18n/use_l10n（默认 true/true）、language_code（默认 en-us）：界面语言。中文界面改 language_code=zh-hans（Django 内置简体中文翻译包，能否完整翻译取决于 Sosse 模板的国际化覆盖程度）；
• use_tz（默认 true）/timezone（默认 UTC）：按需改 timezone=Asia/Shanghai，影响管理界面时间展示与定时爬取的解释；
• datetime_format（默认 N j, Y, P，形如 "Oct. 24, 2026, 9:41 a.m."）：Django 格式串，可改 Y-m-d H:i。

5.6 对外数据通道（[webserver]）

• atom_feed_size（默认 200）/atom_access_token（默认空）：搜索结果提供 Atom 订阅；关闭匿名搜索时，可用 token 让订阅器免登录拉取（?token=<值> 方式附加）；
• atom_archive_bin_passthrough（默认 true）：Atom 里二进制归档链接直接返回文件本体而非归档元数据页；
• csv_export（默认 true）/csv_export_size（默认 200）：CSV 导出开关与条数上限；
• admin_page_size（默认 100）：管理后台列表页每页条数；
• crawl_status_autorefresh（默认 5 秒）：Crawl queue/Crawlers 页面的自动刷新间隔，轮询压力敏感可调大；
• data_upload_max_memory_size（默认 2621440 字节）/data_upload_max_number_fields（默认 1000）：Django 上传保护阈值，接口提交大文档时按需调大。

5.7 爬虫并发与网络（[crawler]）

• crawler_count（默认空=CPU 核数/2，实测 12 核环境即 6 worker）：并发 worker 数。I/O 密集型爬取可以调到接近 CPU 核数；内存紧张的 2C 小机建议固定为 2~3；
• proxy（默认空）：爬虫统一出网代理，格式 http://192.168.0.1:8080/；内网爬取外网资源受限环境必配；
• user_agent（默认 Sosse）：爬虫 UA。礼貌起见保留产品标识；fake_user_agent_* 三项（browser/os/platform）可启用 fake-useragent 库随机轮换 UA（⚠️ 启用前提是 user_agent 置空）；
• requests_timeout（默认 10 秒，0 表示不超时）：静态抓取超时。慢速站点可上调，但不要设 0（会挂死 worker）；
• max_redirects（默认 5）：静态抓取最大重定向次数（官方注明该值仅对 requests 模式精确生效）。

5.8 浏览器渲染抓取（[crawler]）

• default_browser（默认 chromium）：自动检测模式下优先使用的浏览器，可 firefox；
• chromium_options（默认 --enable-precise-memory-info --disable-default-apps --headless）：Chromium 命令行参数。root 运行爬虫需追加 --no-sandbox；无 swap 小内存环境建议追加 --disable-dev-shm-usage；
• firefox_options（默认 --headless）；
• screenshots_size（默认 1920x1080）：截图分辨率；
• js_stable_time（默认 0.1 秒）/js_stable_retry（默认 100）：浏览器加载后等待 DOM 稳定的策略，重 JS 站点可调大 js_stable_time；
• browser_idle_exit_time（默认 5 秒）：空闲自动退出浏览器进程释放内存；
• browser_crash_sleep（默认 1.0 秒）/browser_crash_retry（默认 1）：浏览器崩溃后的重试节奏。

5.9 内容处理与限额（[crawler]）

• fail_over_lang（默认 english）：语言检测失败时的解析回退语言（实测爬取中文短页面时出现 lang_iso_639_1=vi/de 的误检，正是该回退与检测器小样本偏差所致；对检索影响有限，因 PostgreSQL 向量按检出语言生成后仍可命中）；
• hashing_algo（默认 md5）：判断页面内容是否变化的哈希算法，用于重爬去重与再索引触发；
• max_file_size（默认 1000000 kB≈1GB）：可索引文件上限；max_html_asset_size（默认 50000 kB≈50MB）：HTML 附带资源（css/图片）下载上限。磁盘紧张环境调小这两个值能显著控制归档体积；
• tmp_dl_dir（默认 /var/lib/sosse/downloads）/browser_config_dir（默认 /var/lib/sosse/browser_config）：临时下载与浏览器 profile 目录，可挂独立数据盘；
• dl_check_time（默认 0.1 秒）/dl_check_retry（默认 2）：下载动作的检测节奏；
• css_parser（默认 internal，可改 cssutils）：CSS 解析实现，官方注明"HTML 快照样式错乱时可切换 cssutils"；
• worker_crash_retry（默认 1）：单页处理 worker 崩溃重试次数。

5.10 参数速查：最常改的 10 项

六、生产配置模板

6.1 模板一：内网知识库（8GB 内存 / 200GB SSD / 中小团队）

[common]
secret_key = <由 sosse-admin generate_secret 生成>
debug=false
db_name=sosse
db_user=sosse
db_pass=q1w2e3r4
db_host=127.0.0.1
db_port=5432

[webserver]
anonymous_search=false
allowed_host=sosse.intra.example.com
language_code=zh-hans
timezone=Asia/Shanghai
datetime_format=Y-m-d H:i
default_page_size=20
csv_export=true
links_no_referrer=true

[crawler]
crawler_count=4
requests_timeout=15
max_file_size=200000
max_html_asset_size=20000
fail_over_lang=english

适用说明：只爬内网站点，关闭匿名搜索，域名绑定 FQDN，截图/快照保留但限制大文件，4 worker 兼顾速度与内存。

6.2 模板二：公网垂直搜索（16GB 内存 / 500GB SSD / 对外开放）

[common]
secret_key = <由 sosse-admin generate_secret 生成>
debug=false
db_pass=q1w2e3r4

[webserver]
anonymous_search=true
allowed_host=*
online_check_url=https://www.quzuo.net/
online_check_timeout=2.0
online_check_cache=once
default_search_redirect=
atom_feed_size=100
max_page_size=100
admin_page_size=50

[crawler]
crawler_count=6
proxy=http://192.168.0.1:8080/
requests_timeout=20
max_redirects=5
browser_idle_exit_time=10
max_file_size=500000
max_html_asset_size=50000

适用说明：匿名搜索开放，在线判定探针换成可直连的公网站点，爬虫经代理出网，worker 与超时按 16GB 内存档位放宽。

6.3 模板三：2C4G 低配单机（个人自用）

[common]
secret_key = <由 sosse-admin generate_secret 生成>
debug=false
db_pass=q1w2e3r4

[webserver]
anonymous_search=false
default_page_size=10
crawl_status_autorefresh=15

[crawler]
crawler_count=2
requests_timeout=10
max_file_size=100000
max_html_asset_size=10000
browser_idle_exit_time=3
browser_crash_retry=1

适用说明：并发压到 2、空闲浏览器 3 秒退出、归档限额减半，优先保住小内存机器的稳定性。

三档模板关键差异：内存档位主要影响 crawler_count 与浏览器空闲退出时间；磁盘档位主要影响两个 max_*_size 限额；是否对外决定 anonymous_search 与 allowed_host。

七、常见问题（FAQ）

Q1：改了配置为什么没生效？ 配置在进程启动时读取。[webserver] 节改动重启 systemctl restart sosse-uwsgi；[crawler] 节改动重启 systemctl restart sosse-crawler；[common] 节两方共用，两个服务都要重启（逐条执行，每行一个单元）。

Q2：环境变量和配置文件同时设了同一个参数，哪个生效？ 环境变量（SOSSE_ 前缀）优先。本文 3.3 节用 SOSSE_DB_PASS=wrongpass 实测：配置文件密码正确的情况下，dbshell 仍以环境变量的错误密码连接并报 FATAL: password authentication failed，证明覆盖关系。排障时若配置文件值看起来正确却不生效，先检查进程环境里有没有同名 SOSSE_* 变量（cat /proc/<pid>/environ | tr '\0' '\n' | grep SOSSE）。

Q3：secret_key 可以留 CHANGE ME 吗？ 不可以留注释态。default_conf 已自动生成随机值并写入 secret_key = ... 行，保持该行即可；只有从旧版本配置迁移或手工精简配置文件时，才需要用 sosse-admin generate_secret 生成新值填入（实测输出形如 ludl)^aeowdgtiemw#9jk7jdx&qd$&2!14m&slkte5kf6!3-p)）。

Q4：html_snapshot_url 改了之后旧快照打不开？ 该 URL 前缀在抓取时被写进快照 HTML 的内部链接。改前缀只影响新快照，历史快照内链仍指向旧前缀。官方处理方式：改回原值，或对历史页面重新爬取生成新快照（管理后台重新入队，或用 sosse-admin crawl --one-shot 重爬）。

Q5：爬虫把服务器带宽/CPU 占满了怎么限？ 三处下手：crawler_count 降到 2；requests_timeout 保持默认 10 秒避免慢站拖住 worker；如果启用了浏览器渲染，browser_idle_exit_time 调小让空闲浏览器尽快退出。没有全局限速参数，并发数是主要调节杠杆。

Q6：allowed_host 配错了会怎样？ Django 层直接拒绝请求（返回 400 DisallowedHost）。用域名对外服务时把它配成实际 FQDN（如 sosse.example.com），本地调试保持默认 *。

八、参考链接

1. 官方配置文件参考（本文参数表依据）：https://sosse.readthedocs.io/en/stable/config_file.html
2. Django Settings 参考（secret_key/allowed_host 等上游语义）：https://docs.djangoproject.com/en/3.2/ref/settings/
3. 安装指南（配置文件初始化步骤）：https://sosse.readthedocs.io/en/stable/install/pip.html
4. 管理界面文档（参数相关的后台操作）：https://sosse.readthedocs.io/en/stable/admin_ui.html
5. 命令行接口（default_conf/generate_secret 等命令）：https://sosse.readthedocs.io/en/stable/cli.html

站内相关：《Yacy 1.942 介绍与选型指南》。