Novu 自托管部署完全指南VPS 上 Docker Compose 跑起来先把 HOST_NAME 改对【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu把社区版 Novu 用 Docker Compose 部署到一台 VPS 上完成后你会得到一个可以从公网访问的 Dashboardhttp://你的vps-ip:4000以及配套的 API3000和 WebSocket3002入口。全文最容易踩错的一个参数是HOST_NAMEdocker/community/.env.example 第 19 行的默认值是http://localhost本机部署用不改的话 Dashboard 能打开但浏览器里的 API 与 WebSocket 请求仍指向 localhost页面永远无法登录。以下步骤与默认值均取自官方文档 docs/community/self-hosting-novu/deploy-with-docker.mdx 与仓库内docker/community/的源文件。环境清单Novu 自托管部署要放行哪几个端口工具与资源按官方两份文档对齐deploy-with-docker.mdx 的 Prerequisites 一节和 docs/community/self-hosting-novu/overview.mdx 的 System requirements 一节。项目用途是否必须对外放行Docker Compose v2docker compose version可用运行全部服务—curl、opensslsetup 脚本做依赖检查、生成随机密钥—DashboardWeb 控制台是端口4000APIREST APIServer SDK 入口是端口3000WS应用内Inbox实时推送是端口3002Worker后台任务仅容器内健康检查用端口3004compose 未映射宿主端口否MongoDB / Redis / LocalStack(S3)数据与队列compose 内网互通否无宿主端口映射资源基线单 VM 部署overview.mdxNovu 四个服务合计 4 vCPUs、8 GB RAMMongoDB 2 GB RAM、20 GB 磁盘Redis 2 GB RAM 并开启 AOF对象存储 10 GB 起。文档注明这是通用建议可按负载调整。拿到部署文件并自动生成三个安全密钥操作在 VPS 上克隆仓库进入部署目录运行 setup 脚本。若当前目录已有docker-compose.yml和.env.examplesetup.sh 直接使用当前目录不再联网下载已存在的.env只补齐缺失的密钥值不覆盖你已有的配置。# 在 VPS 上执行仓库地址为本文约定的克隆源 git clone https://gitcode.com/GitHub_Trending/no/novu cd novu/docker/community bash setup.sh预期输出脚本先检查curl、docker、openssl与 Compose v2 是否存在然后依次打印Created .env with secure random secrets Setup complete. Starting Novu...随后自动执行docker compose up -d并输出各服务的 localhost 地址VPS 上请把这些地址读成你的公网 IP。如何判断成功部署目录下出现.env且JWT_SECRET、STORE_ENCRYPTION_KEY、NOVU_SECRET_KEY三项不再是空值。这三个值分别用于 API 签发 JWT、加解密密必须 32 字符、SDK 鉴权脚本用openssl rand -hex生成.env权限被设为 600。如果你选择手动克隆仓库而不跑脚本这三个值必须在上线前自行填入否则无法签发/校验令牌。六个容器启动并转为 healthy操作若上一步已自动启动可跳过否则在部署目录执行docker compose up -d预期输出docker compose ps出现 6 个容器redis、mongodb、api、worker、ws、dashboard镜像均为 docker-compose.yml 中固定的ghcr.io/novuhq/novu/*:3.19.0。如何判断成功6 个服务状态依次转为healthy。compose 文件中每个服务都定义了 healthcheck——API、WS、Worker 探测容器内/v1/health-checkDashboard 探测根路径返回 HTTP 200MongoDB 和 Redis 就绪后api、worker、ws才会启动depends_on: condition: service_healthy。把 HOST_NAME 改成公网 IP让 Dashboard 从外部可用为什么先讲这个.env里所有对外地址都由HOST_NAME推导这是整个部署里唯一“默认值只适用于本机”的核心变量。对照 .env.example 第 19 行及下方推导项本机部署值VPS 生产值HOST_NAMEhttp://localhostHOST_NAMEhttp://vps-ip或你的域名其中vps-ip指你这台 VPS 的公网 IP。推导出来的变量如下不改HOST_NAME就全都指向 localhostVITE_API_HOSTNAME${HOST_NAME}:3000 VITE_WEBSOCKET_HOSTNAME${HOST_NAME}:3002 API_ROOT_URL${HOST_NAME}:3000 S3_LOCAL_STACK${HOST_NAME}:4566操作编辑.env将HOST_NAME改为公网地址后重启生效官方文档在修改环境变量后同样使用docker compose up -d重启HOST_NAMEhttp://vps-ipdocker compose up -d预期输出dashboard等依赖该变量的容器被重建docker compose ps重新转为 healthy。如何判断成功在你自己的电脑而非 VPS 本机浏览器打开http://vps-ip:4000能看到 Novu 登录/注册页面。VPS 本机访问localhost:4000成功不算数浏览器端的 API/WS 地址才是HOST_NAME真正作用的位置。关键参数表哪些默认值只适用于本机需要改动的变量一览来源为 .env.example 与 deploy-with-docker.mdx变量默认值建议值不改会坏什么HOST_NAMEhttp://localhost仅本机适用http://vps-ip或域名Dashboard 前端请求 API/WS 全部打到 localhost公网用户无法登录、Inbox 收不到推送JWT_SECRET空必填脚本随机值或openssl rand -hex 32API 无法签发/校验登录令牌STORE_ENCRYPTION_KEY空必填恰好 32 字符openssl rand -hex 16渠道凭据SMTP、短信商等无法加解密NOVU_SECRET_KEY空必填openssl rand -hex 32Server SDK 与 Inbox 鉴权失败MONGO_INITDB_ROOT_PASSWORDsecret强随机密码数据库使用可猜测的默认口令DISABLE_USER_REGISTRATIONfalse生产环境true公网下任何人可注册新账号见加固一节补充一条官方建议REDIS_CACHE_SERVICE_HOST与REDIS_HOST在小规模部署中可取同值规模扩大后建议拆成两个 Redis 实例缓存与队列分离。自检三个访问入口的通过判据访问什么看到什么 成功失败时先查什么http://vps-ip:4000Novu 登录/注册页打不开先查 VPS 防火墙/安全组是否放行 4000官方 VPS Security Considerations 第一条http://vps-ip:3000/v1/health-check正常响应API 的 compose 健康检查路径docker compose logs -f apihttp://vps-ip:3002/v1/health-check正常响应WS 的 compose 健康检查路径docker compose logs -f wsdocker compose ps6 个容器全部healthy停在starting时看对应服务日志Dashboard 起不来通常卡在 API 未 healthyDashboard 能打开但页面白屏、登录报网络错误的回到上一节核对HOST_NAMEVITE_API_HOSTNAME是在容器启动时注入的改完必须docker compose up -d重建容器才生效。加固与边界关闭公开注册并知道官方的取舍操作公网部署默认允许任何能访问 Dashboard 的人注册账号。在.env中加一行并在 API 服务上生效默认值falseDISABLE_USER_REGISTRATIONtrue改完执行docker compose up -d重启。设为true后API 对注册请求返回400 Bad Request与Account creation is disabled见 apps/api/src/app/auth/usecases/register/user-register.usecase.ts已有用户仍可登录默认值定义在 apps/api/src/config/env.validators.ts。官方方案的明确取舍deploy-with-docker.mdx 的 Configuration 一节为简单做了两处折中MongoDB 与各服务跑在同一台机器上官方强烈建议生产部署前先把数据库解耦对象存储用 LocalStack 代替 S3。其他边界文档给出的 VPS 安全清单还包括配置 SSL/TLS 启用 HTTPS、定期更新镜像与主机系统、使用强且唯一的.env密钥、用 Nginx 等反向代理加一层防护若要在反向代理后以子路径如company.com/novu服务需设置GLOBAL_CONTEXT_PATH及各服务的API_CONTEXT_PATH、WS_CONTEXT_PATH等变量且这些变量要设置在 Novu 所有服务上。另注意自托管版本不支持社交登录GitHub、Google 等只能用邮箱密码访问账号overview.mdx。演进建议服务跑稳之后第一优先事项按 overview.mdx 的多 VM 推荐把 MongoDB 迁到独立实例其次再考虑缓存与队列的 Redis 分离。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考