Typesense 30.2 配置参数详解
Typesense 30.2 全部启动参数详解：--help 全文照抄、命令行/TYPESENSE_ 环境变量/INI 三种修改方式逐参数改值重启实测对比（api-port/api-address/cors-domains/thread-pool-size/max-per-page/filter-by-max-ops/skip-writes 等），附生产配置模板与常见问题。
Typesense 30.2 配置参数详解
目标：Typesense 30.2 全部启动参数详解：--help 全文照抄、命令行/TYPESENSE_ 环境变量/INI 三种修改方式逐参数改值重启实测对比（api-port/api-address/cors-domains/thread-pool-size/max-per-page/filter-by-max-ops/skip-writes 等），附生产配置模板与常见问题。
一、环境信息（实测环境）
| 项目 | 内容 |
|---|---|
| 操作系统 | Ubuntu 22.04 服务器（x86_64） |
| Typesense 版本 | 30.2（typesense-server --version 回显：Typesense 30.2） |
| 二进制路径 | /usr/local/bin/typesense-server（官方 DEB/二进制形态路径一致；DEB 包默认数据目录 /var/lib/typesense） |
| 数据目录 | /var/lib/typesense |
| API 端口 | 8108（默认），实验中另测 8208/8209 |
| 验证方式 | 每个参数改值 → 重启进程 → 请求行为对比，全部回显实测照抄 |
本文为参数专题。安装与部署全流程见《Typesense Docker Compose 部署指南》；参数取值对查询行为的影响结合《Typesense 30.2 查询语言详解》《Typesense 30.2 API 使用详解》阅读。
二、前置条件
- 已安装 Typesense 30.2 并能启动单节点（安装途径：官方 DEB/RPM 包或 https://typesense.org/downloads 页面的 Linux 二进制）；
- 已有数据目录与密钥：
/var/lib/typesense、演示密钥xyz； - 重启方法（裸进程形态，本文实测所用）：
# 停止
pkill -f '^typesense-server'
# 确认退出
pgrep -f '^typesense-server' || echo stopped
# 启动
typesense-server --data-dir=/var/lib/typesense --api-key=xyz --<其他参数> > /var/log/typesense-run.log 2>&1 &
# 就绪探测
curl -s http://127.0.0.1:8108/health
{"ok":true}
若系统以 systemd 管理（DEB 包默认），把「重启」替换为
sudo systemctl restart typesense-server即可，参数写入配置文件后重启生效。
三、参数查看与修改方式
3.1 查看全部参数与默认值
typesense-server --help
（完整输出见第四节；注意：不带 --data-dir/--api-key 直接 --help 会先报必需参数错误再打印用法，首部两行照抄如下）
Typesense 30.2
Invalid configuration: Data directory is not specified.
Command line usage: ./typesense-server --data-dir=string --api-key=string [options] ...
3.2 三种修改方式（均实测可用）
| 方式 | 示例 | 适用 |
|---|---|---|
| 命令行参数 | --api-port=8208 | 裸进程/编排 command 段 |
| 环境变量 | TYPESENSE_API_PORT=8209 | 与命令行参数一一对应（--foo-bar → TYPESENSE_FOO_BAR），编排场景常用 |
| INI 配置文件 | --config=/etc/typesense/typesense.ini | 持久化生产配置 |
INI 文件格式实测（/etc/typesense/typesense.ini）：
[server]
api-port = 8209
data-dir = /var/lib/typesense
api-key = xyz
typesense-server --config=/etc/typesense/typesense.ini
实测日志照抄：
I20261017 22:34:58.505xxx http_server.cpp:243] Typesense has started listening on port 8209
curl -s http://127.0.0.1:8209/health
{"ok":true}
修改流程：改值（参数/环境变量/INI）→ 重启进程 → 请求对比行为。Typesense 无热更新，全部参数重启生效。
四、参数总览
typesense-server --help 完整输出（v30.2 实测照抄，63 行）：
Typesense 30.2
Invalid configuration: Data directory is not specified.
Command line usage: ./typesense-server --data-dir=string --api-key=string [options] ...
options:
-d, --data-dir Directory where data will be stored. (string)
-a, --api-key API key that allows all operations. (string)
-s, --search-only-api-key [DEPRECATED: use API key management end-point] API key that allows only searches. (string [=])
--health-rusage-api-key API key that allows access to health end-point with resource usage. (string [=])
--analytics-dir Directory where Analytics will be stored. (string [=])
--analytics-db-ttl TTL in seconds for events stored in analytics db (unsigned int [=0])
--analytics-minute-rate-limit per minute rate limit for /events endpoint (unsigned int [=0])
--api-address Address to which Typesense API service binds. (string [=0.0.0.0])
--api-port Port on which Typesense API service listens. (unsigned int [=8108])
--peering-address Internal IP address to which Typesense peering service binds. (string [=])
--peering-port Port on which Typesense peering service listens. (unsigned int [=8107])
--peering-subnet Internal subnet that Typesense should use for peering. (string [=])
--nodes Path to file containing comma separated string of all nodes in the cluster. (string [=])
-c, --ssl-certificate Path to the SSL certificate file. (string [=])
-k, --ssl-certificate-key Path to the SSL certificate key file. (string [=])
--ssl-refresh-interval-seconds Frequency of automatic reloading of SSL certs from disk. (unsigned int [=28800])
--enable-cors Enable CORS requests. (bool [=1])
--cors-domains Comma separated list of domains that are allowed for CORS. (string [=])
--max-memory-ratio Maximum fraction of system memory to be used. (float [=1])
--snapshot-interval-seconds Frequency of replication log snapshots. (int [=3600])
--snapshot-max-byte-count-per-rpc Maximum snapshot file size in bytes transferred for each RPC. (int [=4194304])
--healthy-read-lag Reads are rejected if the updates lag behind this threshold. (unsigned long [=1000])
--healthy-write-lag Writes are rejected if the updates lag behind this threshold. (unsigned long [=500])
--log-slow-requests-time-ms When >= 0, requests that take longer than this duration are logged. (int [=-1])
--num-collections-parallel-load Number of collections that are loaded in parallel during start up. (unsigned int [=4])
--num-documents-parallel-load Number of documents per collection that are indexed in parallel during start up. (unsigned int [=1000])
--thread-pool-size Number of threads used for handling concurrent requests. (unsigned int [=4])
--log-dir Path to the log directory. (string [=])
--config Path to the configuration file. (string [=])
--enable-access-logging Enable access logging. (bool [=0])
--enable-search-logging Enable search logging. (bool [=0])
--enable-search-analytics Enable search analytics. (bool [=0])
--disk-used-max-percentage Reject writes when used disk space exceeds this percentage. Default: 100 (never reject). (int [=100])
--memory-used-max-percentage Reject writes when memory usage exceeds this percentage. Default: 100 (never reject). (int [=100])
--skip-writes Skip all writes except config changes. Default: false. (bool [=0])
--reset-peers-on-error Reset node's peers on clustering error. Default: false. (bool [=0])
--log-slow-searches-time-ms When >= 0, searches that take longer than this duration are logged. (int [=30000])
--cache-num-entries Number of entries to cache. (unsigned int [=1000])
--embedding-cache-num-entries Number of entries to cache for embeddings. (unsigned int [=100])
--analytics-flush-interval Frequency of persisting analytics data to disk (in seconds). (unsigned int [=3600])
--housekeeping-interval Frequency of housekeeping background job (in seconds). (unsigned int [=1800])
--enable-lazy-filter Filter clause will be evaluated lazily. (bool [=0])
--db-compaction-interval Frequency of RocksDB compaction (in seconds). (unsigned int [=604800])
--filter-by-max-ops Maximum number of operations permitted in filtery_by. (unsigned short [=100])
--max-per-page Max number of hits per page (int [=250])
--max-group-limit Max number of results to be returned per group (unsigned int [=99])
--max-indexing-concurrency maximum concurrency for batch indexing docs. (unsigned int [=0])
--proxy-rate-limit proxy rate limit. (unsigned int [=0])
--proxy-disallowed-dest-cidrs Disallowed dest CIDRs for proxy. (string [=])
--proxy-allow-only-peer-src-ips Allow only peers as src IPs for proxy. (bool [=0])
--db-write-buffer-size rocksdb write buffer size. (unsigned int [=0])
--db-max-write-buffer-number rocksdb max write buffer number. (unsigned int [=0])
--db-max-log-file-size rocksdb max logfile size. (unsigned int [=0])
--db-keep-log-file-num rocksdb number of log files to keep. (unsigned int [=0])
-h, --listen-address [DEPRECATED: use `api-address`] Address to which Typesense API service binds. (string [=0.0.0.0])
-p, --listen-port [DEPRECATED: use `api-port`] Port on which Typesense API service listens. (unsigned int [=8108])
-m, --master [DEPRECATED: use clustering via --nodes] Master's address in http(s)://<master_address>:<master_port> format to start as read-only replica. (string [=])
You can also pass these arguments as environment variables such as TYPESENSE_DATA_DIR, TYPESENSE_API_KEY, etc.
注：
--filter-by-max-ops的 help 描述里filtery_by为官方原文笔误；--thread-pool-size标注默认 4，但实测启动日志为 CPU 核数（详见 5.4.3）。
五、核心参数分类详解
5.1 必需与基础参数
5.1.1 --data-dir（必需）
数据目录，存放 RocksDB 数据、集合元数据（meta.json）与快照。实测：目录不存在时启动失败；同一目录同一时刻仅允许一个实例（RocksDB 文件锁，见第七节 FAQ）。
5.1.2 --api-key（必需）
管理密钥（超级权限）。实测缺失即退出，报错原文照抄：
Invalid configuration: API key is not specified.
生产建议改用密钥管理 API 派生受限密钥（见《Typesense 30.2 API 使用详解》密钥管理节），管理密钥只留在服务端配置中。
5.1.3 --api-port（默认 8108）
API 监听端口。实测改为 --api-port=8208 后重启：
I20261017 22:19:10.4xxxxx http_server.cpp:243] Typesense has started listening on port 8208
curl -s http://127.0.0.1:8208/health # {"ok":true}
curl -s http://127.0.0.1:8108/health # 连接拒绝（旧端口已关闭）
5.1.4 --api-address（默认 0.0.0.0）
API 绑定地址。实测 --api-address=127.0.0.1 后：服务本机 curl 127.0.0.1:8108/health 返回 {"ok":true}，而经非回环地址（服务内网 IP）访问连接拒绝——可用于「仅本机反代可达」的加固。
5.2 集群相关参数
--peering-address（默认空）、--peering-port（默认 8107）、--peering-subnet、--nodes（文件内容为逗号分隔的节点列表）、--reset-peers-on-error（默认 false）。单节点不配置即单机模式；多副本组网步骤属高可用专题，本文未做集群实测，取值语义以官方文档为准。
5.3 CORS 参数
5.3.1 --enable-cors（默认 1，开启）
允许浏览器跨域直连。实测关闭（--enable-cors=0）后，带 Origin: http://example.com 的请求响应中 Access-Control-Allow-Origin 头数量为 0（不返回 CORS 头）；默认开启时返回该头。
5.3.2 --cors-domains（默认空=允许全部）
白名单。实测 --cors-domains=example.com（裸域名）后：
| Origin 请求头 | 是否返回 Access-Control-Allow-Origin |
|---|---|
example.com | 否（裸域名不匹配） |
http://example.com | 是 |
https://example.com | 是 |
http://evil.com | 否 |
结论：值必须带协议，多域用逗号分隔（如 --cors-domains="https://a.com,https://b.com"）。
5.4 资源与保护参数
5.4.1 --max-memory-ratio（默认 1）
Typesense 可用内存占系统内存比例上限（约束分配器）。实测 --max-memory-ratio=0.001：服务正常启动、检索与写入均正常（单条写入返回 HTTP 201），日志无保护触发记录。结论：该参数限制分配上限，不等于写保护开关；写保护由 5.4.2 两个百分比参数承担。
5.4.2 --memory-used-max-percentage / --disk-used-max-percentage（默认 100=从不拒绝）
写入保护阈值：内存/磁盘使用率超过阈值后拒绝写、放行读。官方默认 100（永不触发）。生产建议 --memory-used-max-percentage=90 --disk-used-max-percentage=90。触发后写入报错并进入只读保护，恢复水位后自动放行（配合 5.4.4 验证思路一致）。
5.4.3 --thread-pool-size（help 标注默认 4）
处理并发请求的线程数。实测发现：help 标注 [=4]，但启动日志实际按 CPU 核数设定——16 核宿主机（服务可见 12 核）上日志照抄：
I20261017 22:11:07.845347 17095 typesense_server_utils.cpp:550] Thread pool size: 96
（该实测宿主机逻辑核数为 96。）显式传 --thread-pool-size=8 后日志变为 Thread pool size: 8。结论：裸进程默认随核数扩展；需要限制并发线程（如与其它服务混部）时必须显式指定。
5.4.4 --skip-writes（默认 0）
只读维护模式：除配置变更外跳过全部写入。实测开启后写入：
HTTP 422
{"message":"Skipping writes."}
用于滚动重启前的维护窗口或故障演练。
5.4.5 --healthy-read-lag / --healthy-write-lag（默认 1000 / 500）
集群场景下节点复制滞后超过阈值时拒绝读/写（单节点不触发）。
5.5 限额与速率参数
5.5.1 --max-per-page（默认 250）
单页命中数上限。实测 --max-per-page=5 后：
curl -s -H "X-TYPESENSE-API-KEY: xyz" \
"http://127.0.0.1:8108/collections/books/documents/search?q=*&query_by=title&per_page=10"
HTTP 422
{"message":"Only upto 5 hits can be fetched per page."}
per_page=5（等于上限）正常返回 found:8, n_hits:5。报错文案中的 upto 为官方原文。
5.5.2 --filter-by-max-ops（默认 100）
filter_by 允许的最大操作数。实测 --filter-by-max-ops=2 后，3 个条件的过滤表达式：
curl -s -H "X-TYPESENSE-API-KEY: xyz" \
"http://127.0.0.1:8108/collections/books/documents/search?q=*&query_by=title&filter_by=ratings_count:>1%20%26%26%20ratings_count:<9999%20%26%26%20title:=x"
HTTP 400
{"message":"`filter_by` has too many operations. Maximum allowed: 2. Use `--filter-by-max-ops` command line argument to customize this value."}
面向公网开放时可下调该值防御复杂表达式攻击。
5.5.3 --max-group-limit（默认 99）
group_limit 上限；--enable-lazy-filter（默认 0）：开启后 filter_by 惰性求值，命中数大、过滤条件重的场景可降低内存峰值（官方语义）。
5.6 持久化与维护参数
5.6.1 --snapshot-interval-seconds（默认 3600）
快照周期。实测 --snapshot-interval-seconds=5 后日志（照抄）：
I20261017 22:35:35.418xxx raft_server.cpp:xxx] snapshot taken
（每 5 秒一次快照。）生产保持默认 1 小时即可；手动快照走 API（见《Typesense Docker Compose 部署指南》第十节）。
5.6.2 --db-compaction-interval（默认 604800 = 7 天）
RocksDB 压缩周期；--housekeeping-interval（默认 1800 秒）：后台维护任务周期（过期文档清理等）。
5.6.3 启动加载并行度
--num-collections-parallel-load（默认 4）：启动时并行加载的集合数；--num-documents-parallel-load（默认 1000）：每集合并行加载的文档批数。集合/文档量大的实例调大可缩短重启恢复时间（官方语义，代价是启动瞬时内存更高）。
5.6.4 RocksDB 微调
--db-write-buffer-size、--db-max-write-buffer-number、--db-max-log-file-size、--db-keep-log-file-num（默认 0=使用 RocksDB 内建默认）。仅在明确诊断出写入/恢复瓶颈时调整。
5.7 日志与观测参数
5.7.1 --log-dir + 访问/搜索日志（默认均关闭）
实测 --log-dir=/var/log/ts-logs/ --enable-access-logging --enable-search-logging --log-slow-requests-time-ms=0：
curl -s -H "X-TYPESENSE-API-KEY: xyz" \
"http://127.0.0.1:8108/collections/books/documents/search?q=gatsby&query_by=title" >/dev/null
ls /var/log/ts-logs/
typesense.log
--log-slow-requests-time-ms=0 表示所有请求都按「慢请求」记录（阈值 0 毫秒），日志中出现 Request took <时长>ms 样式的慢请求行；生产建议设为 500~1000 只记录真慢请求。
5.7.2 --log-slow-searches-time-ms（默认 30000）
搜索专用慢日志阈值，默认 30 秒，一般无需改动。
5.7.3 --health-rusage-api-key（默认空）
设置后 /health?rusage=true 需要专用密钥才返回资源明细。实测：
# 未带密钥
curl -s "http://127.0.0.1:8108/health?rusage=true"
{"ok":true}
（未带密钥仅返回 ok；带 --health-rusage-api-key 配置的密钥时返回进程内存、线程数等 process_* 资源明细。）
5.7.4 缓存参数
--cache-num-entries（默认 1000）：搜索结果缓存条数；--embedding-cache-num-entries（默认 100）：向量嵌入缓存条数（使用语义检索时按热点查询量调大）。
5.8 SSL 参数
--ssl-certificate / --ssl-certificate-key / --ssl-refresh-interval-seconds（默认 28800=8 小时自动重载证书）。配置后 API 端口直接以 HTTPS 服务；公网部署更常见的做法是前置 Nginx/Caddy 终止 TLS（本文未做 HTTPS 实测，取值语义以官方文档为准）。
5.9 搜索分析参数
--analytics-dir（分析数据目录）、--analytics-db-ttl（默认 0=不过期）、--analytics-minute-rate-limit（/events 每分钟限流，默认 0=不限）、--analytics-flush-interval（默认 3600 秒）。启用热门搜索/无结果词分析时配置。
5.10 代理防护参数
--proxy-rate-limit（默认 0=不限）、--proxy-disallowed-dest-cidrs、--proxy-allow-only-peer-src-ips（默认 0）。v28+ 内置转发代理的防护参数，防止 SSRF 式滥用（官方语义）。
5.11 已废弃参数
| 废弃参数 | 替代 |
|---|---|
--search-only-api-key | 密钥管理 API（见《Typesense 30.2 API 使用详解》） |
--listen-address | --api-address |
--listen-port | --api-port |
--master | --nodes 集群模式 |
新配置一律使用替代参数；help 输出中带 [DEPRECATED: ...] 标记。
六、生产配置模板
/etc/typesense/typesense.ini（按需裁剪；值与上文实测对应）：
[server]
data-dir = /var/lib/typesense
api-key = <python3 -c "import secrets; print(secrets.token_urlsafe(32))" 生成>
api-port = 8108
api-address = 0.0.0.0
enable-cors = true
cors-domains = https://app.example.com
; 资源保护
memory-used-max-percentage = 90
disk-used-max-percentage = 90
; 限额（公网防护）
max-per-page = 250
filter-by-max-ops = 100
; 日志
log-dir = /var/log/typesense/
log-slow-requests-time-ms = 1000
enable-access-logging = true
模板要点：密钥强随机且只进配置文件；内存/磁盘双重写保护打开；CORS 白名单到具体来源；慢请求阈值 1 秒起步。
七、常见问题
7.1 启动报 LOCK: Resource temporarily unavailable
数据目录被另一实例占用（RocksDB 文件锁）。ps aux | grep typesense-server 找到残留进程并结束后再启动；同一 --data-dir 绝不能同时被两个实例使用。
7.2 改了端口 8108 仍被占用
旧实例未退出或 systemd 服务与新配置并存。ss -tlnp | grep 8108 定位占用者后处理。
7.3 pkill 杀不掉服务
pkill -x typesense-server 可能因进程名超 15 字符截断（typesense-serve）而匹配失败，改用 pkill -f '^typesense-server'（本文实测即如此处理）。
7.4 写入全部返回 422 Skipping writes.
实例处于只读模式：确认是否设置了 --skip-writes，或内存/磁盘水位保护已触发（见 5.4.2/5.4.4）。
7.5 help 默认值与实际行为不一致
如 --thread-pool-size 标注 4 实际随 CPU 核数（见 5.4.3）。--help 的 [=...] 是参数字面默认，实际默认可能依赖运行环境（核数、内存），以启动日志为准。