企业官网建设流程全解析

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 上，完成后你会得到一个可以从公网访问的 Dashboard（http://<你的vps-ip>:4000），以及配套的 API（3000）和 WebSocket（3002）入口。全文最容易踩错的一个参数是HOST_NAME：docker/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 一节。

资源基线（单 VM 部署，overview.mdx）：Novu 四个服务合计 4 vCPUs、8 GB RAM；MongoDB 2 GB RAM、20 GB 磁盘；Redis 2 GB RAM 并开启 AOF；对象存储 10 GB 起。文档注明这是通用建议，可按负载调整。

拿到部署文件并自动生成三个安全密钥

操作：在 VPS 上克隆仓库进入部署目录，运行 setup 脚本。若当前目录已有docker-compose.yml和.env.example，setup.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-check，Dashboard 探测根路径返回 HTTP 200；MongoDB 和 Redis 就绪后api、worker、ws才会启动（depends_on: condition: service_healthy）。

把 HOST_NAME 改成公网 IP，让 Dashboard 从外部可用

为什么先讲这个：.env里所有对外地址都由HOST_NAME推导，这是整个部署里唯一“默认值只适用于本机”的核心变量。对照 .env.example 第 19 行及下方推导项：

其中<vps-ip>指你这台 VPS 的公网 IP。推导出来的变量如下（不改HOST_NAME就全都指向 localhost）：

VITE_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_NAME=http://<vps-ip>

docker 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：

补充一条官方建议：REDIS_CACHE_SERVICE_HOST与REDIS_HOST在小规模部署中可取同值，规模扩大后建议拆成两个 Redis 实例（缓存与队列分离）。

自检：三个访问入口的通过判据

Dashboard 能打开但页面白屏、登录报网络错误的，回到上一节核对HOST_NAME：VITE_API_HOSTNAME是在容器启动时注入的，改完必须docker compose up -d重建容器才生效。

加固与边界：关闭公开注册，并知道官方的取舍

操作：公网部署默认允许任何能访问 Dashboard 的人注册账号。在.env中加一行并在 API 服务上生效（默认值false）：

DISABLE_USER_REGISTRATION=true

改完执行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