# 服务器配置
这些参数用于控制和微调 Typesense 中的各种默认服务器设置。
Typesense Cloud
在 Typesense Cloud 中，我们会自动为您管理以下服务器参数。但如果您需要自定义其中任何参数，请发送邮件至 support@typesense.org，简要说明需要更改的使用场景，我们可以从后台为您进行调整。
# 使用命令行参数
可以通过 --parameter=value 的形式向服务器传递命令行参数。
# 通用参数
| 参数 | 是否必填 | 描述 |
|---|---|---|
--config | 否 | 配置文件的路径。如果使用此参数，可以在配置文件中定义所有其他命令行参数。 |
--api-key | 是 | 一个具有全部操作权限的引导管理员 API 密钥。请务必使用 密钥管理 API 创建具有特定 ACL 的额外密钥。 注意：不要将此管理员 API 密钥暴露给浏览器 JS 客户端：使用 密钥管理 API 创建仅限搜索或限定范围的 API 密钥。 |
--data-dir | 是 | 数据将存储在磁盘上的目录路径。 |
# CORS (跨域资源共享)
| 参数 | 是否必需 | 描述 |
|---|---|---|
--enable-cors | 否 | 允许 JavaScript 客户端直接从浏览器访问 Typesense。 |
--cors-domains | 否 | 允许跨域访问的域名列表，用逗号分隔。例如：https://example.com,https://example2.com (不要包含末尾斜杠！) |
# 分析功能
| 参数 | 是否必需 | 描述 |
|---|---|---|
--enable-search-analytics | 否 | 允许聚合搜索查询用于查询分析。默认值：false |
--analytics-dir | 否 | Typesense 存储分析数据的目录。 |
--analytics-flush-interval | 否 | 搜索查询聚合数据持久化到存储的间隔时间（秒）。默认值：3600 (每小时) |
--analytics-minute-rate-limit | 否 | 每分钟可发送的最大分析事件数量。默认值：5 |
# 日志记录
| 参数 | 是否必需 | 说明 |
|---|---|---|
--log-dir | 否 | 默认情况下，Typesense 将日志输出到 stdout 和 stderr。如需启用文件日志记录，请提供日志目录路径。日志会写入该目录下的 typesense.log 文件。 |
--enable-access-logging | 否 | 将 API 请求及对应 IP 地址记录到 log-dir 目录下的 typesense-access.log 文件中。默认值: false |
--enable-search-logging | 否 | 在搜索请求生命周期开始时，将搜索 API 请求及负载记录到 log-dir 目录下的 typesense.log 文件中。默认值: false |
--log-slow-requests-time-ms | 否 | 记录耗时超过此值（毫秒）的请求。默认值: -1 表示禁用慢请求记录。您也可以通过 /config API 动态启用慢请求记录。 |
# 网络配置
| 参数 | 是否必填 | 描述 |
|---|---|---|
--api-address | 否 | Typesense API 服务绑定的地址。默认值: 0.0.0.0 |
--api-port | 否 | Typesense API 服务监听的端口。默认值: 8108 |
--peering-address | 否 | Typesense 节点间通信服务绑定的内部 IP 地址。如果未指定此参数，Typesense 将尝试使用第一个可用的内部 IP。 |
--peering-port | 否 | Typesense 节点间通信服务监听的端口。默认值: 8107 |
--peering-subnet | 否 | Typesense 用于节点间通信的内部子网，例如: 192.160.1.0/24。 |
# SSL / HTTPS
| 参数 | 是否必填 | 说明 |
|---|---|---|
--ssl-certificate | 否 | SSL 证书文件路径。必须同时定义 ssl-certificate-key 才能启用 HTTPS。 |
--ssl-certificate-key | 否 | SSL 证书密钥文件路径。必须同时定义 ssl-certificate 才能启用 HTTPS。 |
--ssl-refresh-interval-seconds | 否 | 从磁盘自动重新加载 SSL 证书的频率。默认值: 8 * 60 * 60 (8小时)。 |
# 集群配置
| 参数 | 是否必填 | 说明 |
|---|---|---|
--nodes | 否 | 包含集群中所有节点的逗号分隔字符串的文件路径。 |
--reset-peers-on-error | 否 | 在不可恢复的集群错误时强制重置节点的对等节点。这可能导致间歇性数据丢失，仅作为最后手段尝试。 |
# 资源使用
| 参数 | 是否必需 | 描述 |
|---|---|---|
--thread-pool-size | 否 | 用于处理并发请求的线程数。默认值：NUM_CORES * 8。 |
--num-collections-parallel-load | 否 | 启动时并行加载的集合数量。默认值：NUM_CORES * 4。 |
--num-documents-parallel-load | 否 | 启动时每个集合并行索引的文档数。默认值：1000。 |
--cache-num-entries | 否 | 用于存储搜索查询响应的LRU缓存条目数。默认值：1000。 |
--disk-used-max-percentage | 否 | 当已用磁盘空间超过此百分比时拒绝写入。默认值：100（永不拒绝）。 |
--memory-used-max-percentage | 否 | 当已用内存超过此百分比时拒绝写入。默认值：100（永不拒绝）。 |
--healthy-read-lag | 否 | 如果更新滞后超过此阈值，则拒绝读取。默认值：1000。 |
--healthy-write-lag | 否 | 如果更新滞后超过此阈值，则拒绝写入。默认值：500。 |
--snapshot-interval-seconds | 否 | 复制日志快照的频率。默认值：3600（用于follower恢复）。注意：频繁快照有助于从冷启动中更快恢复。但如果对于大型数据集此值设置过低，重复快照实际上可能会减慢follower恢复速度。 |
--db-compaction-interval | 否 | 自动数据库压缩的频率。默认值：604,800（7天）如果您频繁删除和重新创建集合，可以考虑将此值设置为24小时。 |
--skip-writes | 否 | 以不读取Raft日志写入的模式启动Typesense。当服务器因某些最近的错误写入而崩溃，您想暂时跳过这些写入时很有用。 |
--filter-by-max-ops | 否 | filter_by子句中允许的最大操作符数量。默认值：100 |
--max-per-page | 否 | 每页允许的最大命中数。默认值：250 |
# 使用配置文件
除了命令行参数外，您还可以通过配置文件或环境变量来配置 Typesense 服务器。
命令行参数的优先级最高，而环境变量的优先级最低。
我们的 Linux DEB/RPM 包会将配置文件安装在 /etc/typesense/typesense-server.ini。
配置文件采用简单的 INI 格式：
您可以在 typesense-server.ini 文件中使用上表中的任何参数，只需去掉前面的 -- 前缀。
# 使用环境变量
如果您希望使用环境变量，也可以实现。环境变量与上述文档中的命令行参数相对应：只需使用大写字母和下划线代替连字符，并在变量名前加上 TYPESENSE_ 前缀。
例如，使用 TYPESENSE_DATA_DIR 对应 --data-dir 参数。