企业官网建设流程全解析

• 可观测性
• 后端
• 前端
• 运维

Kener 是一款开源的现代化状态页（Status Page）应用，支持实时监控、在线率统计、事件管理与告警通知。本文以官方 v3 部署文档为骨架，完整讲解 Kener 的源码（NPM/PM2）、Docker 容器、子路径部署与 Railway 一键部署四条落地路径，并结合当前仓库的 Dockerfile、docker-compose.yml、入口服务 等源码，深入解释构建过程、数据卷挂载、环境变量作用与健康检查机制，帮助你在本地或生产环境快速、稳妥地把 Kener 跑起来。

部署方式总览

Kener 官方提供了多种部署方式，按运维习惯和场景可划分为四类：

在开始之前，无论选择哪条路径，都必须先完成前置条件准备与环境变量设置这两步基础工作。

前置条件（Prerequisites）

根据官方部署文档，部署 Kener 前需要确保以下依赖就绪：

• Node.js 20 及以上版本：官方 v3 文档要求 Node.js 20+；需要注意，当前仓库 package.json 的engines字段已声明node >= 24.14.0，建议部署时优先使用 Node.js 24 或更高版本，避免运行时因 API 差异报错。
• npm：随 Node.js 一并安装。
• Sqlite3：默认数据库 SQLite 依赖它；若你计划使用 Postgres 或 MySQL，则此项可省略。
• ./database目录：确保项目根目录下存在database目录（SQLite 数据库文件、Knex 迁移与种子数据都落在这里）。使用 Docker 时同样要求在挂载前先创建。
• 环境变量：先完成环境变量配置/docs/content/v3/environment-vars.md)。既可以用.env文件，也可以作为命令行参数传入；生产部署时务必加上NODE_ENV=production。

此外，从当前仓库实现来看，Redis 已是运行时强依赖：redisConnector.ts 在读取REDIS_URL时会直接throw new Error("REDIS_URL is not defined in environment variables")，且 BullMQ 任务队列、缓存与调度器都依赖 Redis（见 docker-compose.yml 中redis服务）。因此无论是源码部署还是 Docker 部署，都需要准备一个可用的 Redis 实例。

环境变量：部署前必须掌握的清单

官方 v3 文档列出了 Kener 运行所需的环境变量（完整说明见 environment-vars.md/docs/content/v3/environment-vars.md)），此处归纳为下表：

几个容易踩坑的细节：

• 邮件双通道优先级：同时配置 SMTP 与 Resend 时，Kener 会优先走 SMTP（官方文档明确说明）。SMTP_PORT=465通常对应隐式 SSL（SMTP_SECURE: 1），而 587 / 25 端口通常使用 STARTTLS（SMTP_SECURE: 0）。
• 无需认证的 SMTP：如果邮件服务商不需要用户名密码，将SMTP_USER与SMTP_PASS设为-即可。
• 监控中的密钥引用：环境变量还能充当"监控密钥"。例如监控请求https://api.example.com/users需要携带Authorization: Bearer $CLIENT_SECRET头时，可先在环境变量（或.env）中定义CLIENT_SECRET=your-api-key，在监控配置里用$CLIENT_SECRET占位引用，避免把密钥明文写进监控定义。

.env文件写法示例（可直接复制到项目根目录）：

KENER_SECRET_KEY=please_change_me PORT=4242 GH_TOKEN=your-github-token RESEND_API_KEY=re_sometoken KENER_BASE_PATH=/status ORIGIN=http://localhost:3000

关于数据库，默认 SQLite 数据库文件会创建在根目录database文件夹下（默认文件名为kener.sqlite.db），详情见数据库配置文档/docs/content/v3/database.md)。Kener 支持 SQLite、Postgres、MySQL 三类数据库，应用每次启动时都会自动把迁移执行到最新版本（对应逻辑见 scripts/main.ts 的runMigrations/runSeed）。

方式一：NPM 源码部署

在满足前置条件、项目根目录已存在database目录的前提下，源码部署只需三步：

npm i npm run build # 构建前端 npm run start

• npm run build在 package.json 中定义为node scripts/build-sveltekit.js && node scripts/build-server.js，即先用 Vite 构建 SvelteKit 前端，再用 esbuild 打包服务端为build/main.js。
• npm run start实际执行node build/main.js，它负责监听端口、执行数据库迁移与种子数据、启动调度器与任务队列，并注册优雅停机处理（SIGTERM/SIGINT）。

方式二：PM2 进程守护

生产环境不想引入 Docker 时，可以用 PM2 托管 Kener 进程，保证进程异常退出后自动拉起：

npm i npm run build # 构建前端 pm2 start main.js

与 NPM 方式唯一的差异在于启动命令：把npm run start换成pm2 start main.js。PM2 会以守护进程方式运行main.js，并提供日志、进程列表与重启策略。建议配合NODE_ENV=production环境变量使用。

方式三：Docker 部署

官方镜像

Kener 官方镜像有两个来源（以仓库内 v3 文档为准）：

docker.io/rajnandan1/kener:latest # Docker Hub ghcr.io/rajnandan1/kener:latest # GitHub Packages

仓库根目录的 Dockerfile 是多阶段构建（builder → final），默认基于node:24-alpine，也支持--build-arg VARIANT=debian切换到 Debian Slim 变体；最终镜像会安装sqlite、tzdata、curl等运行期依赖，并切换到非 root 的node用户运行（USER node），同时为/bin/ping设置cap_net_raw能力以支持 ICMP 探测类监控。

数据卷挂载（Volumes）

持久化数据必须挂载到宿主机目录，否则容器重建后数据丢失：

• $(pwd)/uploads：挂载一个宿主目录以持久化图片上传；
• $(pwd)/database：使用 SQLite 时，挂载一个宿主目录以持久化数据库文件。

同时确保根目录下存在./database和./uploads目录。

SQLite 示例

mkdir database uploads

docker run \ -v $(pwd)/database:/app/database \ -v $(pwd)/uploads:/app/uploads \ -p 3000:3000 \ -e "KENER_SECRET_KEY=somesecretkey" \ -e "ORIGIN=http://localhost:3000" \ rajnandan1/kener

使用 .env 文件

环境变量除了用-e逐个传入，也可以整体放到.env文件中：

mkdir database uploads

docker run \ -v $(pwd)/database:/app/database \ -v $(pwd)/uploads:/app/uploads \ --env-file .env \ -p 3000:3000 \ rajnandan1/kener

也可以直接使用仓库提供的Docker Compose编排（参考根目录 docker-compose.yml）。当前仓库的 Compose 内置了redis服务（redis:7-alpine，带健康检查），kener服务默认镜像为rajnandan1/kener:latest，并预留了 Postgres（postgres:16-alpine）与 MySQL（mariadb:11）的可选服务块，取消注释并配置DATABASE_URL即可启用。运行方式：

docker compose up -d

如果希望基于本地 Dockerfile 构建而非拉取镜像，可使用开发版 Compose：

docker compose -f docker-compose.dev.yml up -d --build

Postgres 示例

使用 Postgres 时不需要database目录（数据库由 Postgres 管理），但仍需uploads目录：

mkdir uploads

docker run \ -p 3000:3000 \ -v $(pwd)/uploads:/app/uploads \ -e "KENER_SECRET_KEY=somesecretkey" \ -e "DATABASE_URL=postgresql://myuser:mypassword@localhost:5432/mydatabase" \ -e "ORIGIN=http://localhost:3000" \ rajnandan1/kener

MySQL 示例

MySQL 同样不需要database目录：

mkdir uploads

docker run \ -p 3000:3000 \ -v $(pwd)/uploads:/app/uploads \ -e "KENER_SECRET_KEY=somesecretkey" \ -e "DATABASE_URL=mysql://root:password@mysql-container-2.orb.local:3306/kener-2" \ -e "ORIGIN=http://localhost:3000" \ rajnandan1/kener

子路径（Base Path）部署

默认 Kener 运行在/，但可以通过KENER_BASE_PATH部署到/status或其他任意子路径（比如与既有站点共享域名、由反向代理分发时）。完整说明见环境变量文档中的 KENER_BASE_PATH 章节/docs/content/v3/environment-vars.md)。

三个关键约束（官方文档原文强调）：

• 子路径不能以/结尾，且必须以/开头；
• 该环境变量在构建期与运行期都必须存在；
• 必须使用相同的子路径构建前端。

子路径之所以必须在构建期注入，是因为 SvelteKit 前端路由的base需要在打包时确定；从源码看，服务端同样依赖它做路径拼接——例如 resolver.ts 会基于KENER_BASE_PATH为资源 URL 加前缀，commonController.ts 也会用KENER_BASE_PATH作为 Cookie 路径。仓库内的 resolver.test.ts 还覆盖了"自动折叠尾斜杠"（/status/归一为/status）的测试用例。

以部署到/status为例，先构建镜像时注入子路径：

docker build --build-arg KENER_BASE_PATH=/status -t kener .

再运行容器（--env-file中的.env需包含KENER_BASE_PATH=/status及运行时必需变量）：

docker run -p 3000:3000 --env-file .env -v $(pwd)/database:/app/uploads -v $(pwd)/database:/app/database kener

注意：上方示例同时挂载了uploads与database两个目录；如果你的实例不需要图片上传功能，uploads卷可以省略，但database卷在 SQLite 场景下必须保留。

生产环境的健康检查与启动细节

Kener 的容器入口与主进程实现中包含若干值得生产环境注意的细节：

• 健康检查端点：scripts/main.ts 在 Express 上注册了GET /healthcheck，依次探测数据库与 Redis，返回{ "status": "ok"|"degraded", "db": bool, "redis": bool }。传入?strict=1时，任一组件不可用会返回 HTTP 503；默认恒返回 200，避免健康检查驱动的重启逻辑在依赖挂掉时反复重启。Docker 镜像内置的HEALTHCHECK指令正是请求${PORT}${KENER_BASE_PATH}/healthcheck（见 Dockerfile）。
• 请求体上限：docker-entrypoint.sh 会把BODY_SIZE_LIMIT默认设为3M（SvelteKit adapter-node 默认 512K 对图片上传不够用）。
• 文档索引：当镜像带文档构建（WITH_DOCS=true）时，entrypoint 会先执行index-docs把文档索引进 Redis；若未配置REDIS_URL会打印警告并继续启动。
• 自动迁移：每次启动都会执行 Knex 迁移到最新版本并运行种子数据（runMigrations/runSeed），因此无需手动执行npm run migrate；源码部署时如需手动迁移，可用npm run migrate。

Railway 一键部署

如果你不想维护服务器，Kener 官方还提供了 Railway 模板，支持一键部署。点击官方文档中的 "Deploy on Railway" 按钮，按模板页面提示填写环境变量（至少包括KENER_SECRET_KEY、ORIGIN，以及当前版本需要的REDIS_URL）即可完成上线。此方式对团队快速验证或中小流量场景非常合适。

部署完成后：验证与排障建议

1. 访问验证：浏览器打开http://<host>:3000（或子路径部署时打开/status），能看到状态页与管理后台即说明启动成功；控制台应输出Kener is running on port 3000!。
2. 健康检查：执行curl -s http://<host>:3000/healthcheck，期望得到{"status":"ok","db":true,"redis":true}。
3. 常见问题：
   • 启动即报REDIS_URL is not defined：当前版本强依赖 Redis，检查是否配置REDIS_URL（参考 redisConnector.ts）。
   • 图片上传失败：确认uploads目录已挂载且容器内可写，必要时调大BODY_SIZE_LIMIT。
   • 子路径 404：检查KENER_BASE_PATH是否在构建期与运行期都设置、是否以/开头且无尾斜杠。
   • 邮件无法发送：确认RESEND_API_KEY或SMTP_*配置完整，并注意"SMTP 优先于 Resend"的优先级规则。

至此，从依赖准备、环境变量、源码构建、Docker 容器化到子路径与 PaaS 部署，Kener 的全部官方部署路径均已覆盖。你可以依据自身基础设施情况任选其一，把状态页稳定地跑起来。

• 可观测性
• 后端
• 前端
• 运维