Zulip 开发环境安装指南：Vagrant、WSL 2、直接安装与远程开发的完整路线图

Zulip 开发环境安装指南Vagrant、WSL 2、直接安装与远程开发的完整路线图【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip本指南是 Zulip 开源项目开发环境的安装总览篇系统梳理从「本机安装」到「远程开发」的全部官方路径推荐新手使用的 VagrantmacOS/Linux与 WSL 2Windows方案、面向有经验开发者的 Linux 直接安装方案以及针对网络不佳场景的远程虚拟机方案。读完本文你将掌握 Zulip 开发环境的最低硬件要求、各安装方式的适用场景与取舍原则、./tools/provision与./tools/run-dev的核心用法并能根据自身网络、存储和操作系统条件选择最合适的落地路径。安装前的硬性要求无论选择哪种安装方式Zulip 开发环境的安装都有两条不可妥协的前提内存至少 2GB 可用 RAM。这是官方对宿主机或远程虚拟机的最低要求Vagrantfile 中的默认配置也与之对应——分配 2 个 CPU 与 2 GiB 内存给客户机。网络全程需要稳定且速度合理的互联网连接。安装过程会下载数百兆字节的依赖Ubuntu 基础镜像、Python 依赖、前端包等如果网络受限需要提前配置代理详见下文「代理配置」。从平台支持看Zulip 开发环境可在macOS、Windows 和 Linux上安装官方推荐 Debian 或 Ubuntu 系的 Linux 发行版作为宿主系统。三种安装路线总览官方将安装方式划分为三条主线它们的取舍逻辑非常清晰安装方式适用平台核心机制优点适用人群Vagrant 开发环境macOS、LinuxWindows 走 VM 路线时为备选创建 Linux 容器默认 Docker provider或虚拟机Zulip 服务器及全部相关服务在其中运行隔离性好、易安装/更新/卸载、久经测试、性能良好首次贡献者首选WSL 2 开发环境Windows在 Windows 子系统 Linux 中直接运行比 VM 更轻量接近原生 Linux 体验Windows 用户的官方首选直接安装Ubuntu/Debian/CentOS/Fedora 等 Linux在宿主 Linux 系统上直接运行./tools/provision无虚拟化开销启动最快有经验的 Linux 用户、网络较慢者官方对首次贡献者的明确建议是macOS 和 Linux 用户使用 Vagrant 方案Windows 用户使用 WSL 2 方案。为什么推荐 Vagrant/WSL 2Vagrant 方案的核心设计思想是创建一个容器或虚拟机并把包含你源代码的 Git 仓库以挂载方式同步进其中。Zulip 服务器和所有相关服务PostgreSQL、Redis、RabbitMQ、Memcached 等都在隔离环境内运行。这样做换来的是极强的可移植性和可靠性——官方文档明确指出Vagrant/Docker 与 WSL 2 这两项技术是他们在服务了数千名开发环境使用者之后基于实际经验挑选出的「最可靠」组合。Vagrant 唯一的代价是给开发服务器带来少量额外开销但换来的是易于安装、更新和卸载一个vagrant destroy即可彻底清理环境。推荐路线一Vagrant 开发环境平台前置条件不同平台的前置条件各不相同详见 docs/development/setup-recommended.mdmacOS安装最新版 Vagrant 与最新版 Docker Desktop。若使用旧版 Docker Desktop可能需要取消勾选 Use gRPC FUSE for file sharing 并回退到osxfs (legacy)文件共享模式否则 provision 会失败典型报错如ERR_PNPM_LINKING_FAILED。Ubuntu/Debian通过 HashiCorp APT 源安装 Vagrant再执行sudo apt install docker.io git安装 Docker 与 GitFedora 使用sudo yum install vagrant git moby-engineArch 从 AUR 安装 Vagrant如yay -S vagrant。其他 Linux 发行版只要支持 Git、Vagrant 和 Docker 即可可参照 Ubuntu/Debian 步骤操作。所有平台都要求至少 2GB 可用 RAM和宽带网络。获取 Zulip 代码安装依赖之前先完成 Git 与 GitHub 的准备Step 0安装 Git、注册 GitHub 账号、创建 SSH key 并添加到账号。然后 fork 官方仓库并克隆到本地$ git clone --config pull.rebase gitgithub.com:YOURUSERNAME/zulip.git $ cd zulip $ git remote add -f upstream https://github.com/zulip/zulip.git--config pull.rebase让后续git pull默认采用 rebase 策略这是 Zulip 协作规范的一部分。upstreamremote 用于与官方主仓库保持同步。启动与首次 provisioning在 zulip 目录下执行$ vagrant up --providerdocker首次运行耗时较长Vagrant 会依次完成下载 Ubuntu 22.04 基础镜像 → 配置容器/虚拟机 → 建立共享目录把你的 Zulip 代码克隆挂载进客户机的~/zulip→ 在客户机内运行./tools/provision脚本下载全部依赖、搭建 Python 环境、初始化默认测试数据库。整个 provisioning 过程称为 provisioning细节记录在 docs/subsystems/dependencies.md。Provisioning 完成后通过vagrant ssh进入环境。注意命令提示符应以(zulip-server) vagrant开头——(zulip-server)前缀是 provisioning 成功的标志如果只有vagrant说明 provisioning 失败需要回到故障排查章节。$ vagrant ssh Welcome to Ubuntu 22.04.3 LTS ... (zulip-server) vagrantvagrant:/srv/zulip$ ./tools/run-dev启动成功后会看到这样的输出其中 9991–9994 是开发环境的四个内部端口Starting Zulip on: http://localhost:9991/ Internal ports: 9991: Development server proxy (connect here) 9992: Django 9993: Tornado 9994: webpack Tornado server (re)started on port 9993 frontend (webpack 5.89.0) compiled successfully in 8054 ms这些端口分工在 tools/run-dev 中定义base_port 99919991 是统一入口的开发服务器代理9992 运行 Django9993 运行 Tornado9994 是 webpack 前端构建服务。在浏览器打开http://localhost:9991/devlogin即可看到 Zulip 开发环境登录页。如果vagrant up因网络不稳定在 provisioning 阶段失败可重试vagrant provision——首次之后vagrant up只负责启动客户机、不再重复 provisioning。Vagrant 生命周期管理更新vagrant provision可随时重新应用最新配置官方建议 rebase 到新版本后出现莫名错误时先重新 provision约一分钟即可完成。暂停/恢复vagrant halt关机vagrant up重新启动重启后重新执行vagrant ssh进入环境。重建先vagrant destroy再重新vagrant up即可从零重建干净环境。卸载vagrant destroy即完成卸载——这是直接安装方案不具备的便利。Windows 上的 Vagrant 备选VirtualBox / Hyper-V如果不想用 WSL 2Windows 用户还有两条基于 Vagrant 的备选路线docs/development/setup-advanced.mdVirtualBox 方案安装 Git for Windows、VirtualBox、VagrantBIOS 开启硬件虚拟化VT-x/AMD-V。注意必须始终以管理员身份运行 Git BASH且要在克隆代码前执行git config --global core.symlinks true启用原生符号链接——Zulip 代码库包含大量 symlink这是开发环境能正常工作的前提。启动命令为vagrant up --providervirtualbox还需安装vagrant-vbguest插件。Hyper-V 方案beta仅限 Windows Enterprise/Pro/Education。以管理员权限执行vagrant up --providerhyperv过程中会提示输入 Windows 管理员凭据因 Hyper-V 机器的 IP 每次重启都会变化每次启动都需重新设置EXTERNAL_HOST环境变量例如export EXTERNAL_HOST$(hostname -I | xargs):9991这也是该方案标记为实验性的原因之一。推荐路线二Windows 上的 WSL 2WSL 2 是 Windows 平台官方首推的开发环境方案要求 WSL 2 版本 ≥ 0.67.6流程如下BIOS 开启虚拟化VT-x 或 AMD-V。安装 WSL 2及一个 Ubuntu WSL 发行版。官方建议为 Zulip新建独立的 WSL 实例避免与已有环境中的node等软件冲突同时必须启用 WSL 2 的 systemd用于管理数据库、缓存等服务随后重启 WSL。以管理员身份打开 Ubuntu shell更新系统并安装服务依赖$ sudo apt update sudo apt upgrade $ sudo apt install rabbitmq-server memcached redis-server postgresql编辑/etc/rabbitmq/rabbitmq-env.conf确认末尾包含以下两行RabbitMQ 只在本机监听 5672 端口NODE_IP_ADDRESS127.0.0.1 NODE_PORT5672务必在 WSL 磁盘内操作cd ~不要在 Windows 挂载盘如/mnt/c/...上运行./tools/provision否则会遭遇权限问题。为 WSL 虚拟机新建 SSH key并添加到 GitHub——Windows 主机上的 SSH key 在 WSL 虚拟机会失效。随后克隆代码并启动环境$ ./tools/provision $ source .venv/bin/activate $ ./tools/run-dev激活后提示符应出现(zulip-server)前缀。日常使用中WSL 2 不需要显式关闭直接关闭终端窗口即可也可用 PowerShell 执行wsl --terminate 环境名终止。恢复开发时只需重新打开 Git BASH、进入 zulip 目录并确认(zulip-server)前缀在缺失时执行source .venv/bin/activate。推荐安装 VS Code 的 Remote - WSL 扩展在 WSL 目录内用code .即可获得无缝的远程编辑体验。推荐路线三Linux 直接安装对于 Linux 用户或网络条件不允许下载虚拟机镜像的场景可以直接在宿主系统上安装docs/development/setup-advanced.md。官方目前支持的平台包括Ubuntu 22.04 / 24.04 / 26.04Debian 12 / 13CentOS 7beta、RHEL 7betaFedora 43 / 44beta注意事项直接安装没有官方支持的卸载流程——这是与 Vagrant 方案最本质的差异。文档明确警告如果希望随时干净卸载请改用 Vagrant。不要以 root 用户运行安装远程服务器场景需先创建带 sudo 权限的普通用户见 docs/development/remote.md。CentOS/Fedora/RHEL 需先安装 python3如yum install pythonDebian/Ubuntu 已内置。安装命令极其简洁全部围绕仓库内的 provision 脚本展开# 从 zulip.git 克隆目录内执行 ./tools/provision source .venv/bin/activate ./tools/run-dev # 启动开发服务器provision 与 run-dev开发环境的两个核心脚本./tools/provision是整个安装体系的中枢Vagrant、WSL 2、直接安装三条路线最终都汇聚到这个脚本上。它负责下载全部依赖、搭建 Python 虚拟环境.venv、初始化默认测试数据库。从源码结构看provision 的逻辑主要由 tools/lib/provision.py 与 scripts/lib/setup-apt-repo 实现官方甚至在文档中提示若你使用的 Debian/Ubuntu 新版本尚未被支持只需修改这两个文件中的少量代码即可自行添加支持并提交 PR。./tools/run-dev则是开发服务器入口tools/run-dev其命令行参数包括--interface设置代理监听的 IP 或主机名与--behind-https-proxy配合反向代理的 HTTPS 模式等。启动后它会代理 9991 端口并自动管理 Django/Tornado/webpack 三个子服务。后续维护直接安装方案更新环境同样靠./tools/provision重跑切换分支后官方也建议重跑一次若无变更数秒内即可完成。环境使用细节统一参考 Step 4: Developing 章节忽略其中 Vagrant 相关内容即可。网络不佳怎么办两条替代路线官方针对慢速网络给出了两条替代路线docs/development/overview.md放弃 Vagrant改用直接安装Vagrant 需要额外下载整个 Ubuntu 虚拟机/容器镜像慢速网络下这是最大的时间黑洞直接安装在 Linux 系统上可跳过这一步。租用云服务器远程开发见下一节。远程开发把开发环境放到云服务器上Zulip 开发环境在远程虚拟机上运行良好docs/development/remote.md尤其适合网络差或本地存储/内存有限的人。官方建议给 Zulip 开发环境独立的虚拟机至少 2GB 内存若虚拟机只跑 Zulip推荐直接安装省去虚拟化层开销若虚拟机还跑别的服务、需要随时卸载 Zulip推荐Vagrant方案。连接与用户配置用ssh连接远程主机macOS/Linux 自带Windows 使用 Git for Windows 附带的 Bash。网络不稳定时可用 Mosh 替代 SSH 以获得更可靠的体验。首次使用需创建带 sudo 权限的非 root 用户$ adduser zulipdev # 按提示设置密码 $ usermod -aG sudo zulipdev # 加入 sudo 组 $ su - zulipdev # 切换到该用户关键差异EXTERNAL_HOST 与 --interface远程开发与本地安装相比核心差异是必须让开发服务器监听对外地址。在运行run-dev前先设置环境变量export EXTERNAL_HOSTREMOTE_IP:9991若服务器有静态 IP官方建议把该命令写入~/.bashrc以免每次忘记。然后启动./tools/run-dev --interface--interface让 Zulip 开发环境可从任意 IP 访问默认只监听 localhost更安全但只适合本机开发。启动后在浏览器访问http://REMOTE_IP:9991/devlogin即可看到 Zulip 开发环境登录页该页面截图见 docs/images/zulip-devlogin.png。更安全的替代SSH 端口转发把开发服务器直接暴露到公网接口有安全风险。更稳妥的做法是用 SSH 端口转发ssh -L 3000:127.0.0.1:9991 usernameremote_server_ip -N随后在本地浏览器访问http://127.0.0.1:3000即可流量全程走加密的 SSH 隧道无需向公网开放任何端口。远程环境下的代码编辑与同步远程开发有两种编辑模式本地编辑 Git 同步在本地克隆 Zulip 并用熟悉编辑器改代码git push origin branchname推到 GitHub 后在远程实例执行git fetch origin git merge origin/branchname拉取变更。远程直接编辑可选命令行编辑器vim/nano、桌面 GUI 编辑器插件如 VS Code Remote - SSH、rmate或 Web IDE文档以 Codeanywhere 为例。新手若想快速上手官方推荐 Web IDE 方案。HTTPS 场景nginx 反向代理某些集成开发如调试 Facebook 的 OAuth2 回调要求开发环境具备合法 SSL 证书而run-dev本身不支持 HTTPS。解决办法是在run-dev前架设 nginx 反向代理先用仓库内的 certbot 封装脚本 scripts/setup/setup-certbot 申请证书方法可选 standalone再将 tools/droplets/zulipdev 这份 nginx 站点配置软链到sites-enabled最后以 HTTPS 模式启动env EXTERNAL_HOSThostname.example.com ./tools/run-dev --behind-https-proxy --interface通过 ~/.zulip-vagrant-config 定制环境Vagrant 方案的各项关键参数都可以通过~/.zulip-vagrant-config配置文件定制。该文件的解析逻辑定义在 Vagrantfile支持以下键配置键默认值作用UBUNTU_MIRROR全局官方镜像指定 Ubuntu 镜像源加速首次下载HTTP_PROXY/HTTPS_PROXY/NO_PROXY无代理设置需配合vagrant-proxyconf插件HOST_PORT9991宿主机访问开发服务器的端口HOST_IP_ADDR127.0.0.1宿主机监听 IP设为 0.0.0.0 可从其他机器访问GUEST_CPUS2分配给客户机的 CPU 数仅 VM 型 provider 生效GUEST_MEMORY_MB2048分配给客户机的内存仅 VM 型 provider 生效指定 Ubuntu 镜像源默认情况下 Vagrant 从全局镜像http://archive.ubuntu.com/ubuntu/下载 Ubuntu 包离镜像源较远会明显拖慢首次安装。在~/.zulip-vagrant-config中添加本地镜像即可加速UBUNTU_MIRROR http://us.archive.ubuntu.com/ubuntu/该值会通过UBUNTU_MIRROR构建参数传给 Docker provider见 Vagrantfile。指定代理需要代理才能上网时先安装插件再写配置$ vagrant plugin install vagrant-proxyconf然后在~/.zulip-vagrant-config中写入未安装插件会导致 Vagrant 直接退出并打印提示HTTP_PROXY http://proxy_host:port HTTPS_PROXY http://proxy_host:port NO_PROXY localhost,127.0.0.1,.example.com,.zulipdev.com需要认证的代理写法类似http://userName:userPassword192.168.1.1:8080。务必仔细核对常见错误是代理只支持http://却写成https://——无效的代理配置会产生各种难以理解的异常排查时最先检查它。若此前vagrant up失败过需先vagrant destroy清理不再需要代理时删除对应两行并vagrant reload即可。自定义 CPU 与内存Docker 等容器型 provider 无需显式分配资源该配置会被忽略但 VirtualBox、VMware Fusion 这类 VM provider 必须显式分配GUEST_CPUS 4 GUEST_MEMORY_MB 8192上述配置分配 4 个 CPU 与 8 GiB 内存。修改后执行vagrant reload重启客户机生效想恢复默认删除这两行即可。自定义端口与对外访问默认宿主机端口 9991对应开发服务器代理与客户机 9991 端口映射Vagrantfile 同时映射了 9994/9995 给 webpack 等服务。修改端口HOST_PORT 9971执行vagrant reload后访问http://localhost:9971/即可。若希望从宿主机之外的其他机器访问开发环境设置HOST_IP_ADDR 0.0.0.00.0.0.0是特殊值表示允许任意 IP 连接。故障排查要点绝大多数安装问题都能通过重新 provision解决Vagrant 环境内执行vagrant provision或在客户机内./tools/provisionWSL 实例内执行~/zulip下的./tools/provision。常用排障工具与信息详见 docs/development/setup-recommended.mdtools/diagnose在客户机/WSL 实例内运行输出环境诊断信息。provision 日志Vagrant 虚拟机在/var/log/provision.logWSL 实例在~/zulip/var/log/provision.log。向社区报告问题时官方特别要求贴出错误输出的开头部分而非仅最后几行并附上宿主操作系统、安装方式Vagrant/WSL、是否使用代理。常见问题速查macOS 上 provision 失败报ERR_PNPM_LINKING_FAILED等错误时把 Docker Desktop 文件共享切回osxfs (legacy)Hyper-V 报Hyper-V could not initialize memory时先关闭其他程序释放内存再重试首次./tools/run-dev请耐心等待前端编译完成。安装完成后的下一步开发环境就绪后官方建议按以下顺序阅读后续文档使用开发环境编辑/刷新工作流——Django/Tornado 进程在 Python 代码保存后自动重启CSS 修改经 webpack 热更新即时生效JS 与 Handlebars 模板改动会触发浏览器自动刷新数据库 schema 变更zerver/models/*.py则需走 Django migrations 流程。测试 与 为 fork 配置 CI测试套件支持单文件/单用例快速运行配合 CI 可大幅优化贡献流程。远程开发用户可继续阅读 远程开发专题 中的编辑器与同步技巧。至此你已经掌握了 Zulip 开发环境从选型、安装、定制到排障的完整链路可以按照自身平台和网络条件选择最优路径开始为 Zulip 贡献代码。【免费下载链接】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），仅供参考