可观测性后端前端运维【免费下载链接】kenerStunning status pages, batteries included!项目地址https://gitcode.com/gh_mirrors/ke/kener点击查看免费下载环境变量是 Kener 状态页应用在不改动任何代码的前提下完成密钥管理、部署设置与运行时行为调优的唯一入口。本文以官方 v4 环境变量文档为核心骨架结合仓库源码src/lib/server/startup.ts、knexfile.ts、src/lib/server/proxy.ts、src/lib/server/tool.ts、Dockerfile等逐项讲解必填变量、可选变量、集成变量与自定义变量的配置方法与底层原理读完你就能为本地开发、Docker 部署和 Kubernetes 生产环境配出一份安全、可运行、可排障的完整环境配置。变量总览Kener 的环境变量可分为四类分类代表变量作用必填KENER_SECRET_KEY、ORIGIN、REDIS_URL决定实例能否安全运行、表单能否提交、后台任务队列是否可用可选PORT、TZ、NODE_ENV、BODY_SIZE_LIMIT、KENER_BASE_PATH、KENER_FORCE_LOCAL_LOGIN、HTTP_PROXY/HTTPS_PROXY/NO_PROXY调整监听端口、时区、请求体上限、子路径托管与出站代理集成邮件Resend/SMTP、数据库、Redis 相关变量打通通知、持久化与任务队列自定义$VARIABLE_NAME形式的任意变量在监控项与告警触发器中安全注入密钥变量在启动时通过dotenv.config()从项目根目录的.env文件加载见 scripts/main.ts随后由npm start启动的入口脚本与 SvelteKit 服务端各自读取。必填变量缺一个都无法安全运行KENER_SECRET_KEY一切安全机制的根密钥用途用于签发 JWT 会话令牌、生成与校验 API 密钥、派生密码哈希HMAC-SHA256以及签名 Cookie。源码中commonController.ts的三处核心调用可以完整印证这一用途链jwt.sign/jwt.verify使用process.env.KENER_SECRET_KEY || DUMMY_SECRET签发并校验会话令牌与找回密码令牌commonController.tsCreateHash用同一密钥对 API 密钥做 HMAC-SHA256 哈希后落库commonController.tsCookieConfig依据ORIGIN是否以https://开头决定 Cookie 的secure标志commonController.ts。要求必须是强随机字符串推荐不少于 32 字符严禁提交进版本控制一旦泄露需立即更换未设置时 Kener 会回退到DUMMY_SECRET默认值并在控制台打印KENER_SECRET_KEY not set, using default (INSECURE)警告——此时会话可被劫持、认证不安全绝不适用于生产。生成强密钥# 使用 OpenSSL openssl rand -base64 32 # 使用 Node.js node -e console.log(require(crypto).randomBytes(32).toString(base64))示例KENER_SECRET_KEYyour-super-secret-random-string-min-32-charsORIGIN生产环境下 CSRF 防护的命脉用途声明 Kener 实例的对外公开 URL。SvelteKit 在生产构建中会校验 POST 表单提交是否来自同源站点不设置ORIGIN所有表单提交登录、注册、设置、管理后台操作都会被拒绝并报Cross-site POST form submissions are forbidden错误。仓库的 src/hooks.server.ts 实现了这一 CSRF 校验当请求为表单内容类型application/x-www-form-urlencoded、multipart/form-data、text/plain且方法为 POST/PUT/PATCH/DELETE 时会比较请求Origin头的主机与当前 URL 主机不一致则直接返回 403。要求必须包含协议http://或https://必须与用户浏览器中访问的地址一致结尾不要带斜杠本地开发vite dev会自动推断无需设置。示例# 本地 Docker 测试 ORIGINhttp://localhost:3000 # 生产环境 ORIGINhttps://status.example.com # 自定义端口 ORIGINhttps://status.example.com:8443 # 配合子路径托管时 ORIGINhttps://example.com⚠️ 生产环境不设置ORIGIN意味着登录、注册、管理面板等一切表单操作全部被拒绝务必在部署时配置。REDIS_URL后台任务队列的连接串用途BullMQ 队列、调度器与缓存依赖 Redis连接串同时被三个组件读取src/lib/server/redisConnector.ts的redisIOConnection()与redisConnection()在REDIS_URL未定义时会直接抛出REDIS_URL is not defined in environment variables错误redisConnector.ts健康检查端点/healthcheck会探测 Redis 的PING响应见 scripts/main.tsDocker 镜像内置的index-docs.ts在启动时把文档索引写入 Redis。要求必须是合法 Redis 连接 URL包含redis://或rediss://协议必须指向可达的 Redis 实例。示例REDIS_URLredis://localhost:6379提示docker-compose.yml中 Redis 使用redis:7-alpine镜像并配置了redis-cli ping健康检查Kener 服务通过depends_on: condition: service_healthy等待 Redis 就绪后再启动见 docker-compose.yml。可选变量按部署场景按需调整KENER_BASE_PATH子路径托管用途让 Kener 运行在反向代理的某个子路径下而非域名根路径。默认/。# 托管在 https://example.com/status KENER_BASE_PATH/status注意事项必须以/开头结尾不能带斜杠需同步修改反向代理配置nginx/Apache 示例见 Reverse Proxy Setup/docs/content/v4/guides/reverse-proxy.md)该变量还会影响 Cookie 的path属性——CookieConfig中let cookiePath !!process.env.KENER_BASE_PATH ? process.env.KENER_BASE_PATH : /见 commonController.ts不设置会导致登录态 Cookie 落在错误的路径上scripts/main.ts中 Express 路由如/healthcheck也会拼接base前缀scripts/main.ts。KENER_FORCE_LOCAL_LOGINOIDC 故障时的紧急后门用途当在 OpenID Connect 设置/docs/content/v4/oidc.md) 中禁用了本地登录而 OIDC 身份提供商又配置错误或不可达时此变量可临时恢复邮箱/密码登录表单帮助管理员重新拿回控制权。默认不设置关闭。KENER_FORCE_LOCAL_LOGINtrue源码印证signin/page.server.ts中const forceLocalLogin process.env.KENER_FORCE_LOCAL_LOGIN true见 src/routes/(account)/account/signin/page.server.ts/account/signin/page.server.ts#L35)只有当该值为字符串true时才放行本地登录。⚠️ 身份提供商恢复可达后务必移除该变量否则本地登录后门长期开放。PORT监听端口默认3000。当端口被占用或需同机运行多服务时调整。PORT8080启动逻辑scripts/main.ts中const PORT process.env.PORT || 3000scripts/main.tsapp.listen(PORT)后打印Kener is running on port PORT!。 生产环境常见做法是PORT3000由 nginx 等反向代理在 80/443 端口对外内部转发到 3000。TZ服务端时区默认UTC。官方建议始终使用 UTC以保持一致用户侧的时区展示由 UI 单独配置。源码印证src/lib/server/startup.ts第一行即process.env.TZ UTCstartup.tsDockerfile 运行时镜像也通过ENV TZUTC固化改动时区可能导致时间戳比较不一致。TZUTCNODE_ENV运行模式取值production性能优化、日志精简默认development详细日志、支持热重载。影响SvelteKit 构建优化、日志冗长度、开发专属特性开关。package.json的dev脚本并行启动vite dev与vite-node src/lib/server/startup.ts两个进程即开发模式形态package.json。# 开发 NODE_ENVdevelopment # 生产 NODE_ENVproductionBODY_SIZE_LIMIT请求体大小上限用途SvelteKit 的请求体大小限制控制服务器愿意接收的最大 payload。默认3M。需要从管理面板上传更大图片或发送更大 API 请求体时调大。格式数字 单位——K千字节、M兆字节或Infinity不限制。BODY_SIZE_LIMIT10M部署细节Dockerfile 在运行时镜像中通过ENV BODY_SIZE_LIMIT3M固化默认值Dockerfile同时 docker-entrypoint.sh 使用export BODY_SIZE_LIMIT${BODY_SIZE_LIMIT:-3M}兜底——原因是 SvelteKit adapter-node 的默认 512K 对图片上传来说太小镜像特意覆盖为 3M。想覆盖时只需向容器传入该变量。HTTP_PROXY / HTTPS_PROXY / NO_PROXY出站代理用途让 Kener 的出站 HTTP 请求统一走正向代理覆盖范围包括API 与 Prometheus 监控探测、webhook/Discord/Slack 触发器、Resend 邮件以及 OIDC discoveryHTTPS 目标通过CONNECT隧道转发。默认不设置直连。HTTPS_PROXYhttp://proxy.internal:3128 HTTP_PROXYhttp://proxy.internal:3128 NO_PROXYlocalhost,127.0.0.1,prometheus.lan,.internal底层实现src/lib/server/proxy.ts在 dotenv 加载完成后调用 Node.js 内置的http.setGlobalProxyFromEnv要求Node.js 24.14.0Docker 镜像基于 Node 24 满足此要求并覆盖全局fetch与全局 http/https agent监控探测用的自定义https.Agent则通过AxiosProxyConfig显式传入proxyEnvproxy.ts。注意 axios 自身的环境代理代码会把 https URL 以明文不走 CONNECT发给代理因此被显式关闭proxy: false改用携带proxyEnv的 Node agent。关键注意事项代理凭据写在 URL 里http://user:passproxy.internal:3128。用户名或密码中的保留字符必须百分号编码#→%23、/→%2F、?→%3F、→%40、:→%3A未编码会改变 URL 的解析终点。同理通过$SECRET替换注入到监控项Proxy URL中的密钥也必须预编码后存储NO_PROXY支持精确主机、host:port、.suffix后缀、*.host通配以及 IPv4 区间10.0.0.1-10.0.0.255不支持 CIDR。建议把局域网 Prometheus 服务器与 Docker daemon 放进来。注意触发器、Resend 与 OIDC 走全局fetch其NO_PROXY匹配规则在非常规条目上与监控项的 agent 可能不同尽量只用主机名与.suffix形式单个 API 或 Prometheus 监控项可设置自己的Proxy URL例如http://user:$PROXY_PASSproxy.internal:3128它会覆盖环境变量对该监控项生效监控项报Failed to establish tunnel to host:443 via …说明代理拒绝连接检查代理凭据或将目标主机加入NO_PROXY。集成变量邮件、数据库与 Redis邮件配置Resend 或 SMTPKener 支持两家邮件提供商对应变量与归属如下变量说明适用RESEND_API_KEYResend API 密钥ResendRESEND_SENDER_EMAIL发件人邮箱ResendSMTP_HOSTSMTP 服务器主机名SMTPSMTP_PORTSMTP 服务器端口SMTPSMTP_USERSMTP 用户名SMTPSMTP_PASS/SMTP_PASSWORDSMTP 密码SMTPSMTP_FROM_EMAIL/SMTP_SENDER发件人邮箱SMTPSMTP_SECURE是否使用 TLS1或0SMTP源码印证emailController.ts的IsResendSetup()要求RESEND_API_KEY与RESEND_SENDER_EMAIL同时存在GetSMTPFromENV()则要求SMTP_HOST、SMTP_PORT、SMTP_USER、发件人、密码五者齐备才返回 SMTP 配置且SMTP_PASS与SMTP_PASSWORD互为别名commonController.ts。发送时优先走 SMTPsmtps.ts的 transporter否则走 ResendemailController.ts。示例ResendRESEND_API_KEYre_123abc... RESEND_SENDER_EMAILalertsstatus.example.com示例SMTPSMTP_HOSTsmtp.gmail.com SMTP_PORT587 SMTP_USERmyemailgmail.com SMTP_PASSapp-specific-password SMTP_FROM_EMAILalertsexample.com SMTP_SECURE1 详细配置与排障见 Email Setup Guide/docs/content/v4/setup/email-setup.md)。数据库配置变量说明默认DATABASE_URL完整数据库连接串sqlite://./database/kener.sqlite.dbDATABASE_POOL_MIN最小连接池PostgreSQL/MySQL0DATABASE_POOL_MAXWeb/请求连接池最大值PostgreSQL/MySQL10DATABASE_WORKER_POOL_MAX后台任务连接池最大值PostgreSQL/MySQL5DATABASE_ACQUIRE_TIMEOUT_MS获取空闲连接的等待超时PostgreSQL/MySQL15000DATABASE_CREATE_TIMEOUT_MS创建新连接的等待超时PostgreSQL/MySQL15000DATABASE_IDLE_TIMEOUT_MS连接空闲关闭时间PostgreSQL/MySQL30000DATABASE_KEEPALIVE连接 TCP keepalivePostgreSQL/MySQLtrue支持的数据库SQLite默认、PostgreSQL、MySQL/MariaDB。示例# SQLite默认 DATABASE_URLsqlite://./database/kener.sqlite.db # PostgreSQL DATABASE_URLpostgresql://user:passwordlocalhost:5432/kener # MySQL DATABASE_URLmysql://user:passwordlocalhost:3306/kener源码级说明源自 knexfile.tsDATABASE_URL按://分割出协议类型sqlite走 better-sqlite3 单文件连接postgresql走pg连接串 keepalivemysql走mysql2URI keepalive非法类型会打印Invalid database type并process.exit(1)PostgreSQL/MySQL 场景下进程内维护两个连接池WEB 池服务 SvelteKit 请求WORKER 池服务 BullMQ 后台任务与调度器防止后台任务突发耗尽页面加载所需的连接。预算公式为副本数 × (web worker) ≤ 数据库 max_connections。SQLite 无真实连接池复用单一连接因此双池不适用默认值刻意偏离 Knex 默认min 0避免 Knex 默认的 2 个常驻连接长期空闲变僵死15 秒的 acquire/create 超时保证数据库故障时快速失败而不是挂起 60 秒DATABASE_KEEPALIVE ! false时启用 keepalive防止云网络Railway、Docker Swarm overlay、k8s静默丢弃空闲 TCP 连接导致池中死连接被反复分发。 迁移指南与连接池调优见 Database Setup Guide/docs/content/v4/setup/database-setup.md)。Redis 配置变量说明必填REDIS_URL完整 Redis 连接串是REDIS_URLredis://localhost:6379 安装方式与性能收益见 Redis Setup Guide/docs/content/v4/setup/redis-setup.md)。自定义环境变量把密钥安全注入监控与告警除内置变量外Kener 支持在监控项与告警触发器中使用自定义环境变量格式为$VARIABLE_NAME美元符号 大写名称从而把敏感凭据安全地隔离在.env中、不落进监控配置。可用的位置监控项 URL监控项 Headers监控项请求体监控项连接串SQL 监控告警触发器 URL告警触发器 Headers告警触发器请求体变量语法# 在 .env 文件中 API_TOKENabc123xyz WEBHOOK_SECRETsecret-key-here DB_PASSWORDsecure-password⚠️ 变量名区分大小写必须与.env中的名称完全一致。源码印证src/lib/server/tool.tsGetWordsStartingWithDollar用/\$\w/g正则从配置文本中提取$NAME形式的占位符GetRequiredSecrets遍历process.env把与占位符同名的环境变量组装成{ find: $NAME, replace: value }列表ReplaceAllOccurrences用正则全局替换replacer 采用函数形式避免密钥值中的$、$1等元字符被误展开ApplySecretsToHeaders对 Header 的 key/value逐项替换——绝不先序列化整段 JSON 再替换防止密钥值里含引号、反斜杠或换行时破坏 JSON、导致整个认证头被静默丢弃key 为空的 Header 会被跳过未解析成功的变量保持原样。以 API 监控为例apiCall.ts构造请求时会先对 url、body、proxy 逐一执行替换再通过ApplySecretsToHeaders处理 HeaderapiCall.ts。示例一带认证的 API 监控环境变量API_KEYsk_live_abc123... API_SECRETsecret_xyz789...监控配置{ url: https://api.service.com/health, headers: [ { key: Authorization, value: Bearer $API_KEY }, { key: X-API-Secret, value: $API_SECRET } ] }运行时Kener 将$API_KEY、$API_SECRET替换为环境中的真实值后发起请求。示例二SQL 监控的安全凭据环境变量DB_USERkener_monitor DB_PASSWORDsecure_db_password DB_HOSTdb.production.com DB_NAMEproduction监控配置{ connectionString: postgresql://$DB_USER:$DB_PASSWORD$DB_HOST:5432/$DB_NAME }示例三带令牌的 Webhook 触发器环境变量TELEGRAM_BOT_TOKEN123456789:ABCdefGHIjklMNOpqrsTUVwxyz PAGERDUTY_TOKENy_NbAkKc66ryYTWUXYEu触发器 URLhttps://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage触发器 Headers[ { key: Authorization, value: Token $PAGERDUTY_TOKEN } ]示例四单字段多变量环境变量API_PROTOCOLhttps API_DOMAINapi.example.com API_VERSIONv2 API_KEYsecret123监控 URL$API_PROTOCOL://$API_DOMAIN/$API_VERSION/status?key$API_KEY结果https://api.example.com/v2/status?keysecret123自定义变量的最佳实践使用描述性名称✅ 推荐$PRODUCTION_API_KEY、$STAGING_DB_PASSWORD、$SLACK_WEBHOOK_TOKEN❌ 不推荐$KEY1、$TOKEN、$VAR按环境分组# 生产数据库 PROD_DB_USERkener PROD_DB_PASSsecret123 PROD_DB_HOSTdb.prod.com # 预发数据库 STAGING_DB_USERkener_test STAGING_DB_PASStest123 STAGING_DB_HOSTdb.staging.com永不提交 .env 文件加入.gitignore.env .env.local .env.*.local用.env.example记录必需变量# 生产 API 监控必需 PRODUCTION_API_KEYyour-key-here PRODUCTION_API_SECRETyour-secret-here # 数据库监控必需 DB_ADMIN_PASSWORDyour-password-here定期轮换密钥生成新密钥 → 更新.env→ 重启 Kener → 验证监控项正常 → 吊销旧密钥。环境变量的加载方式开发环境在项目根目录创建.envKener 启动时自动加载# .env KENER_SECRET_KEYdev-secret-key DATABASE_URLsqlite://./database/kener.sqlite.db # 自定义变量 API_KEYtest-key-123注意.env必须位于项目根目录与package.json同级dotenv.config()默认从当前工作目录加载scripts/main.ts。生产环境方式一系统环境变量export KENER_SECRET_KEYproduction-key npm start方式二.env 文件# 写入生产值 vi .env # 启动自动读取 .env npm start方式三Docker 环境docker-compose# docker-compose.yml services: kener: image: rajnandan1/kener environment: - KENER_SECRET_KEY${KENER_SECRET_KEY} - DATABASE_URLpostgresql://user:passdb:5432/kener env_file: - .env仓库自带的 docker-compose.yml 已给出完整参考必填三项KENER_SECRET_KEY、ORIGIN、REDIS_URL在environment中直接配置邮件与高级变量以注释形式预留REDIS_URL指向同栈内服务名redis://redis:6379。方式四Kubernetes SecretsapiVersion: v1 kind: Secret metadata: name: kener-secrets type: Opaque data: KENER_SECRET_KEY: base64-encoded-value --- apiVersion: apps/v1 kind: Deployment metadata: name: kener spec: template: spec: containers: - name: kener envFrom: - secretRef: name: kener-secrets配置验证与启动日志配置完成后按以下步骤验证启动 Kenernpm start检查启动日志健康时约如下✓ KENER_SECRET_KEY is set ✓ Database connected: postgresql://localhost:5432/kener ✓ Email configured: Resend ✓ Redis connected: redis://localhost:6379 ✓ Kener is running on port 3000!实际源码中启动成功会打印Kener is running on port PORT!scripts/main.ts与 figlet 版本横幅startup.ts。测试关键功能登录管理后台验证KENER_SECRET_KEY创建含$CUSTOM_VAR的监控项验证自定义变量发送测试邮件验证邮件配置。警惕告警日志⚠ KENER_SECRET_KEY not set, using default (INSECURE) ⚠ Variable $API_KEY not found in environment常见问题排查变量未生效症状监控项显示的是字面量$VARIABLE_NAME而非替换后的值。排查检查.env位置必须在项目根目录与package.json同级重启 Kener.env改动需要重启才生效核对变量名必须精确匹配区分大小写核对.env格式使用KEYvalue两侧不能有空格。密钥警告警告KENER_SECRET_KEY not set, using default影响会话可被劫持、认证不安全、不适用于生产。解决立即设置KENER_SECRET_KEY。数据库连接失败错误Database connection failed检查DATABASE_URL格式、数据库服务是否运行、凭据是否有效、网络是否连通、数据库是否存在。测试连接# PostgreSQL psql postgresql://user:passlocalhost:5432/kener # MySQL mysql -h localhost -u user -p kener邮件无法发送检查必需变量是否齐备见上文邮件配置表、变量名有无拼写错误、SMTP 凭据是否有效、发件人邮箱是否已验证部分提供商要求。测试使用管理后台的 Test Email 功能Settings → Email Configuration。安全最佳实践1. 使用强密钥# ✅ 推荐32 字符随机串 KENER_SECRET_KEY$(openssl rand -base64 32) # ❌ 不推荐短且可预测 KENER_SECRET_KEYsecret1232. 环境隔离为开发/预发/生产使用不同凭据# .env.development DATABASE_URLsqlite://./dev.db API_KEYtest-key # .env.production DATABASE_URLpostgresql://prod-host/kener API_KEYprod-key-xxx3. 收紧 .env 权限chmod 600 .env仅属主可读写。4. 生产环境使用密钥管理服务可考虑AWS Secrets Manager、HashiCorp Vault、Azure Key Vault、Google Cloud Secret Manager它们提供自动轮换、访问审计、静态加密与细粒度权限。5. 监控密钥泄露使用git-secrets阻止密钥入库、truffleHog扫描 git 历史、GitHub Secret Scanning自动检测等工具。下一步Email Setup Guide/docs/content/v4/setup/email-setup.md)配置邮件通知Database Setup Guide/docs/content/v4/setup/database-setup.md)搭建 PostgreSQL 或 MySQL 并调优连接池Redis Setup Guide/docs/content/v4/setup/redis-setup.md)启用后台任务处理Monitor Configuration/docs/content/v4/monitors/api.md)在监控项中使用自定义变量Alert Triggers/docs/content/v4/alerting/triggers.md)在 webhook 中使用自定义变量Reverse Proxy Setup/docs/content/v4/guides/reverse-proxy.md)配置子路径与反向代理。赞分享可观测性后端前端运维【免费下载链接】kenerStunning status pages, batteries included!项目地址https://gitcode.com/gh_mirrors/ke/kener点击查看免费下载相关推荐GeminiProChat环境变量配置完全手册从API密钥到安全设置GeminiProChat环境变量配置完全手册从API密钥到安全设置 想要充分利用 GeminiProChat 的强大功能吗掌握 环境变量配置 是解锁全部潜AI 应用前端大模型Kener v4 配置全指南从环境变量、站点设置到反向代理的完整实战手册Kener v4 配置全指南从环境变量、站点设置到反向代理的完整实战手册 本指南以 Kener v4 官方文档 configuration.md/docs/c可观测性后端前端运维OmniRoute 环境变量完全参考指南从必填密钥到生产部署的 27 组配置详解OmniRoute 环境变量完全参考指南从必填密钥到生产部署的 27 组配置详解 本文是 OmniRoute 网关全量环境变量参考手册的中文深度导读基于项目后端API网关LLM 网关人工智能大模型MCP 服务桌面应用上一篇Hyperion高级技巧自定义主题、多语言设置与画中画模式使用教程下一篇Pylint 静态代码分析实战指南推断式检查、渐进式引入与插件生态创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考