Zulip 系统配置详解：/etc/zulip/zulip.conf 全量参数解析与应用方法

Zulip 系统配置详解/etc/zulip/zulip.conf 全量参数解析与应用方法【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip本文基于 Zulip 官方生产文档系统讲解 Zulip 部署级配置文件/etc/zulip/zulip.conf的全部配置段与参数从 Puppet 部署组件、nginx/uwsgi 调优、队列 worker 模式、PostgreSQL 备份到 Tornado 分片与出站代理。读完本文你可以独立完成一次生产环境 Zulip 服务器的配置调整并通过zulip-puppet-apply安全地让改动生效。两个配置文件的关系与改动生效方式Zulip 的部署配置由两个文件分工承担/etc/zulip/zulip.confINI 格式文件用于配置系统与部署属性组件、nginx、代理、备份等即本文的主题/etc/zulip/settings.py用于配置应用本身的 Python 级设置如域名、管理员、EXTERNAL_HOST等参见 settings.md。修改zulip.conf后改动通常不会立即生效需要以 root 身份运行 Puppet 应用命令# /home/zulip/deployments/current/scripts/zulip-puppet-apply对应仓库中的脚本为 scripts/zulip-puppet-apply。该命令会先展示它将做出的配置变更并提示你确认后才实际执行因此调整配置前可以先用 dry-run 心态审视输出。注意如果你使用 Docker 部署 Zulipzulip.conf的大部分能力通过CONFIG_*环境变量暴露应参考 Docker 相关文档对应 docs/production/docker.md而非直接编辑该 INI 文件。布尔值的书写规范当某个设置说set to true / false时true与false是规范写法但以下值都会被视为真不区分大小写1ytyestrueenableenabled任何其他值包括空字符串都视为 false。这一点在迁移或手写配置时值得特别注意填on或enabledtrue之外的奇怪取值都会被判为假。[machine]部署组件与机器级行为puppet_classes逗号分隔的 Puppet class 列表决定在这台服务器上安装哪些组件。最常用的值是zulip::profile::standalone表示单机单宿主部署它包含以下组件参见架构总览中的 Components 一节组件 class职责zulip::profile::app_frontend应用前端nginx uwsgi Tornado 队列进程zulip::profile::memcachedMemcached 缓存zulip::profile::postgresqlPostgreSQL 数据库zulip::profile::rabbitmqRabbitMQ 消息队列zulip::profile::redisRedis缓存/会话等zulip::profile::smokescreen出站 HTTP 代理如果使用基于 Apache 的单点登录认证mod_auth_remote_user需要往列表中加入zulip::apache_sso参见 authentication-methods.md 中 Apache-based SSO 一节。pgroonga设为 true 时启用多语言 PGroonga 全文检索扩展。timesync选择时间同步守护进程默认chrony也支持ntpd与none。除非你的机群统一采用ntpd否则不建议调整。none仅适用于 LXC 这类不允许调整系统时钟的容器——没有准确时钟的 Zulip 服务器无法正确工作。[deployment]升级流程行为deploy_options这些选项会被upgrade-zulip与upgrade-zulip-from-git对应 scripts/upgrade-zulip、scripts/upgrade-zulip-from-git透传给upgrade-zulip-stage-2可取--skip-puppet跳过 Puppet/apt 升级。升级后需要手动运行zulip-puppet-apply。--skip-migrations跳过数据库迁移。升级后需要手动运行./manage.py migrate。--skip-purge-old-deployments跳过清理旧部署目录不加该选项时只保留最近两周的部署。一般生产环境不需要设置这些选项--skip-*主要是为频繁升级的核心开发机减少停机时间。git_repo_url执行从 Git 仓库升级时使用的默认仓库 URL。[application_server]应用服务器与 nginx 调优这是参数最多的一段覆盖 nginx 监听、uwsgi 进程数、队列 worker 模式、S3 上传缓存、KaTeX 数学渲染等。监听与 server_namehttp_only设为 true 时允许 HTTP 访问当 Zulip 位于负责 SSL/TLS 终结的反向代理之后时使用参见 reverse-proxies.md 中 Configuring Zulip to allow HTTP 一节。nginx_listen_port需要监听非 443 端口时设置参见 deployment.md 中 Using an alternate port 一节。nginx_server_name设置 Zulip nginxserver块的server_name指令默认不设置即匹配任意主机名。当你与 Zulip 同机运行其他 nginx 服务、且其配置会抢走发给 Zulip 的请求时才需要设置。要点必须列出 Zulip 服务的所有主机名空格分隔包括 TLS 证书上的主机名否则自动续期会失败。支持 nginx 的尾部通配符例如同时服务example.com及其所有子域[application_server] nginx_server_name example.com *.example.comnginx_worker_processes对应 nginx 的worker_processes默认auto等于可用 CPU 核心数。nginx_worker_connections默认 10000。调大可以让每个 worker 处理更多并发连接代价是 nginx 内存占用增加。经验值该数 × worker 进程数 应大于并发用户数的两倍。队列 worker多进程 vs 多线程模式queue_workers_multiprocess控制 Zulip 队列处理器邮件发送、缩略图、Webhook 等后台任务的运行模式多进程模式吞吐更高但占用更多内存多线程模式可节省约 1.5GiB 内存。默认行为是自动检测从源码 puppet/zulip/manifests/app_frontend_base.pp 可以看到Puppet 侧的判断逻辑是total_memory_mb 3800即默认启用多进程模式——注释解释了为什么用 3800 而不是 4096 作为4GB 机器的判据部分厂商按 4×1000³ 标称 4GB实际只有约 3815MiB。因此官方文档口径是系统内存约 3.5GiB 以上。以下场景建议显式设置为 true/false 覆盖自动判断Docker 部署自动检测看到的是宿主机的内存而不是容器的除非给容器设置了内存限额PostgreSQL / Memcached / Redis / RabbitMQ 使用远程服务器时。从源码结构看队列清单在同文件中集中定义app_frontend_base.pp包括deferred_work、digest_emails、email_mirror、embed_links、embedded_bots、email_senders、deferred_email_senders、missedmessage_emails、missedmessage_mobile_notifications、outgoing_webhooks、thumbnail、user_activity、user_activity_interval。dedicated_soft_reactivation_queue当长期不活跃用户回归时Zulip 需要回填其闲置期间被跳过的消息历史行软激活这个过程可能耗时数秒。默认它与数据导出等可能运行数分钟的任务共享deferred_work队列设为 true 后软激活使用专用队列多进程模式下还有专用 worker 进程不再被这类大任务阻塞。从源码看app_frontend_base.pp开启后soft_reactivation队列会追加到基础队列列表之后。该设置额外消耗一个 worker 进程更适合大服务器小服务器建议保持关闭。文件描述符与连接上限service_file_descriptor_limitSupervisor 允许各进程使用的文件描述符数对应 supervisord 的minfds默认 40000。如果部署规模极大数十万级并发用户Django 进程可能触顶并拒绝客户端连接。调高此值在虚拟化环境Docker、Proxmox LXC中通常还需要同步调整系统级限制。uwsgi_listen_backlog_limit覆盖 uwsgi 默认 128 的连接 backlog。uwsgi_processes覆盖 uwsgiDjango进程数。默认按内存阶梯取值源码 app_frontend_base.pp 中的完整阶梯为系统内存默认 uwsgi 进程数 3000 MiB3 3000 MiB4 6000 MiB6 12000 MiB8 24000 MiB16rolling_restart设为 true 时./scripts/restart-server对应 scripts/restart-server逐个重启 uwsgi 进程而非一次性全部重启。代价是略增内存、且不同请求可能短暂由不同版本代码处理收益是显著减少重启期间客户端收到的 502。S3 上传后端缓存三参数以下三项仅在 S3 存储后端启用时生效参数默认值作用s3_memory_cache_size1MB缓存索引的内存大小约可存 8000 条索引项s3_disk_cache_size200MB缓存内容的磁盘大小是缓存尺寸的主要控制手段s3_cache_inactive_time30 天条目自上次使用后的最长缓存时间因缓存内容不可变它只是内容磁盘占用的辅助上限队列 worker 数量thumbnail_workers图片缩略图 worker 数默认 1。大量超大图片同时上传时缩略图队列会积压表现为未处理图片显示加载转圈此时可调大。email_senders_workers邮件发送 worker 数默认 1。仅在超大安装中批量入队大量邮件时需要调大。从源码结构看app_frontend_base.pp[application_server]段中所有以_workers结尾的键都会被通用解析为队列名 - worker 数默认 1因此这两个参数的命名必须遵守该约定。其他应用服务器参数nameserver启用 S3 后端时nginx 代理 S3 下载需要显式 DNS 服务器来解析 S3 主机名。默认读取/etc/resolv.conf此设置用于覆盖。access_log_retention_daysnginx 与应用访问日志保留天数默认 14。katex_server设为 false 可关闭独立的 KaTeX 数学渲染服务省一点内存代价是数学公式渲染显著变慢——单条消息中包含几十个公式块时可能直接发送失败。katex_server_portKaTeX 服务端口默认 9700。源码中可见两者默认值app_frontend_base.pp。custom_ca_path当认证提供方使用自定义 CA 时填入 PEM 编码 CA 证书的.crt文件绝对路径建议存放于/etc/zulip/Zulip 才能对其发起请求。注意一旦设置了该路径Zulip 将改用操作系统 CA 证书库而非内置库可信根集合可能有细微差异。[postgresql]数据库行为与备份性能参数effective_io_concurrency、listen_addresses分别覆盖 PostgreSQL 同名 GUC 参数。random_page_costZulip 默认设为 1.1适合 SSD如果服务器使用机械盘应改回 PostgreSQL 上游默认值 4.0。version当前使用的 PostgreSQL 版本。不要手工修改请使用 PostgreSQL 升级工具。温备复制warm standbyreplication_primary在温备副本上设为应从中进行流式复制的主库主机名。replication_user副本向主库认证使用的用户名。认证方式由主库pg_hba.conf决定若采用密码认证可为postgresql_replication_password密钥位设置密码。备份策略参数Zulip 默认在所有非复制主机与所有温备副本上执行每晚wal-g备份备份工具详见 export-and-import.md 的 Database-only backup tools。相关开关skip_backups设为 true 时禁止本机执行每晚备份。通常只在拥有多个温备副本时设置避免每个副本各备份一次。backups_disk_concurrency备份时并发磁盘读数量默认 1。若在副本上备份可以承受影响其他磁盘 I/O且 SSD 随机读性能良好可以提高。backups_directory未配置 S3 密钥时改为向该本地磁盘路径做每日备份目录属主应为postgres。官方不推荐将其用于灾难恢复——除非目录与数据库不在同一块盘上否则数据库丢失时备份大概率一并丢失。适合 NAS 挂载点、有外部进程把数据拷走的场景或纯粹用于最近应用层数据变更的时点分析。backups_incremental两次全量备份之间做多少次增量delta备份S3 备份默认 0本地盘备份默认 6。backups_storage_class上传到 S3 时使用的存储类别。默认STANDARD多数部署改用STANDARD_IAS3 Standard-IA总成本更低也支持REDUCED_REDUNDANCY但不建议生产使用。backups_compression_method备份压缩算法默认lz4快但压缩率一般。其他选项lzma压缩最好但最慢、zstd与brotli折中。搜索字典与 SSLmissing_dictionaries在初始建库时设为 true则使用 PostgreSQL 标准pg_catalog.english文本搜索配置而不是 Zulip 改进版的停用词集合数据库建成后此设置不再生效。ssl_ca_file/ssl_cert_file/ssl_key_file分别填入用于验证客户端连接的 CA 证书、保护客户端连接的服务端公钥证书、对应私钥的 PEM 文件路径。ssl_mode验证服务端证书的模式。PostgreSQL 默认prefer不提供任何安全收益如果使用证书认证强烈建议设为require或更高取值范围以 PostgreSQL 的sslmode文档为准。[memcached]参数默认值说明memory服务器总内存的 1/8MB覆盖 memcached 可用内存max_item_size1m单个缓存项大小上限仅当某组织用户数超过 2 万时才需要调整size_reportingfalse开启对象大小统计。每次存取有小开销但让 memcached_exporter 能上报精确的条目大小分布[tornado_sharding]把大型组织分流到多个 Tornado 实例Tornado 负责 Zulip 的 WebSocket 长连接层。这段配置的键决定启动多少个 Tornado 实例以及哪些用户被映射到哪个实例。每个 Tornado 实例监听独立端口从 9800 开始向上编号单个 Tornado 实例通常可承载 1000–1500 个并发活跃用户视消息量而定。按组织名分配端口键为端口号值为空格分隔的 subdomain 名或完全限定主机名后者用于 使用REALM_HOSTS的组织[tornado_sharding] 9800 realm-a realm-b 9801 realm-c 9802 realm-host.example.net按主机名正则分配端口键以_regex结尾值为对完全限定主机名匹配的正则[tornado_sharding] 9800_regex ^realm-(a|b)\.example\.com$ 9801_regex ^other(-option)?\.example.com$巨型组织跨多分片超大组织可以把多个端口用_连接在同一个键里让该组织的流量分布在多个 Tornado 分片上[tornado_sharding] 9800 small-realm 9801_9802 very-large-realm生效流程与底层实现分片配置修改后先运行scripts/zulip-puppet-apply然后必须再运行scripts/refresh-sharding-and-restart 才能真正生效。其底层逻辑在 scripts/lib/sharding.py脚本读取/etc/zulip/zulip.conf的tornado_sharding段生成两个文件——/etc/zulip/nginx_sharding_map.confnginx 的map $host $tornado_server规则把每个组织的主机名/正则映射到http://tornado98xxupstream正则用~*前缀表示不区分大小写匹配/etc/zulip/sharding.jsonDjango 侧的shard_map主机名 → 端口与shard_regexes正则 → 端口数据供后端判断某用户应连到哪个 Tornado。该脚本还强制端口必须从 9800 起连续编号源码中assert ports expected_ports单分片时只生成指向默认 upstream 的 map。当sharding.json或 nginx map 发生变化时脚本会打印Updated sharding; run scripts/refresh-sharding-and-restart提示相关设置解析入口见 scripts/lib/zulip_tools.py。[loadbalancer]外部负载均衡器对接ips外部负载均衡器的 IP 或 CIDR 段列表逗号分隔。只有来自这些地址的X-Forwarded-For与X-Forwarded-Proto才会被信任。rejects_http_requests设为 true 表示来自负载均衡器 IP、但没有携带X-Forwarded-Proto头的请求一律按 HTTPS 处理。这是一个安全漏洞设置除非负载均衡器会单方面拒绝非加密 HTTP 连接或对其返回 301。注意 Zulip 的 HSTS 头在这里不构成防护——API 客户端不遵守 HSTS所以负载均衡器绝不能把任何未加密进来的请求转发给 Zulip。[http_proxy]Smokescreen 出站代理Zulip 所有出站 HTTP 流量包括库直连而非应用层发出的请求都会经过 [Smokescreen](https://smokescreen.io 风格的安全代理)总述见 deployment.md 的 Customizing the outgoing HTTP proxy。从源码看app_frontend_base.ppPuppet 将代理地址注入 Supervisor 为每个进程设置的HTTP_PROXY/HTTPS_PROXY环境变量当 host/port 恰为默认值localhost:4750时才会自动安装zulip::smokescreenclass。各参数参数默认值说明hostlocalhost出站 HTTP CONNECT 代理的主机名或 IPport4750上述代理的 TCP 端口listen_address127.0.0.1Smokescreen 绑定监听的 IPenable_for_camo自动是否让 Camo图片外链代理也走 Smokescreen。Camo 本身已带私有网段拒绝逻辑通常无需路由设为 true/false 可覆盖默认策略默认仅在非本地主机上的 Smokescreen之外才走代理allow_addresses/allow_ranges/deny_addresses/deny_ranges全部私有地址默认拒绝逗号分隔的 IP/CIDR 规则allow 规则覆盖 deny 规则如 127.0.0.0/8、192.168.0.0/16 等私有网段默认全拒[sentry]与[email_gateway][sentry]organization/projectSentry 部署钩子deploy hook使用的组织与项目名配合 deployment.md 的 Sentry deploy hook 使用。[email_gateway]listen收件邮件网关 SMTP 服务器的绑定地址可以是纯端口号或address:port形式IPv6 地址必须用方括号包裹如[2001:db8::1]:25。默认监听所有地址IPv4 与 IPv6的 25 端口。该设置仅作用于网关的本地投递模式轮询polling模式不受影响。常用默认值速查表配置项所在段默认值timesyncmachinechronynginx_listen_portapplication_server443nginx_worker_processesapplication_serverautonginx_worker_connectionsapplication_server10000queue_workers_multiprocessapplication_server内存 3.5GiB 时自动为 trueuwsgi_processesapplication_server按内存 3 ~ 16 阶梯service_file_descriptor_limitapplication_server40000uwsgi_listen_backlog_limitapplication_server128s3_memory_cache_size/s3_disk_cache_size/s3_cache_inactive_timeapplication_server1MB / 200MB / 30 天thumbnail_workers/email_senders_workersapplication_server均 1access_log_retention_daysapplication_server14katex_server_portapplication_server9700random_page_costpostgresql1.1SSD 取向backups_incrementalpostgresqlS30本地盘6backups_compression_methodpostgresqllz4memcached memory/max_item_sizememcached总内存 1/8 / 1mTornado 端口起点tornado_sharding9800 起连续http_proxy host/porthttp_proxylocalhost/4750email_gateway listenemail_gateway所有地址的 25 端口小结配置变更的标准作业流程编辑/etc/zulip/zulip.conf只改动对应段的键值布尔值使用true/false以 root 运行scripts/zulip-puppet-apply核对它展示的变更清单并确认执行若改动的是[tornado_sharding]追加运行scripts/refresh-sharding-and-restart若涉及 PostgreSQL 升级类字段如version走 upgrade.md 提供的专用流程而不是手工改配置。整套配置的解析入口在 Puppet 层puppet/zulip/manifests/app_frontend_base.pp 负责应用服务器段队列、uwsgi、代理、KaTeX 等scripts/lib/sharding.py 负责分片映射文件生成配合 scripts/lib/supervisor.py 生成 Supervisor 进程定义构成了zulip.conf从 INI 文本到运行中进程的完整落地链路。【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考