在 Easypanel 上一键部署 Manifest模板文件、环境变量与自托管模型网关实战指南【免费下载链接】llm-gatewayConnect Your Agents And Harnesses With Any Provider 项目地址: https://gitcode.com/GitHub_Trending/manifest7/llm-gatewayManifest 是一个开源的 AI 模型路由网关它把 OpenAI 兼容的 API 客户端统一收敛到一个端点再按你的规则把请求路由到自有 API Key、订阅服务、本地模型和自定义 Provider同时把用量数据保存在你自己的基础设施中。本文围绕仓库中的 Easypanel 部署模板 展开完整讲解模板文件的结构、生成逻辑、全部环境变量及其底层源码依据并给出模板部署与手动部署两条可落地的路径。读完本文你将能基于 Easypanel 快速自托管一个 Manifest 实例理解每个关键配置项的作用并具备用健康检查与首启冒烟流程验证部署的能力。一、模板目录是什么面向 upstream 的 Easypanel 模板deploy/easypanel/template/目录存放的是 Manifest 项目为上游 easypanel-io/templates 模板仓库准备的提交文件。它由两个文件组成index.ts模板生成器负责产出服务定义服务类型、镜像、域名、环境变量、挂载卷meta.yaml模板元数据包含名称、描述、安装指引、变更日志、配置 Schema、特性与标签。按模板 README 的说明向上游提交时只需把这两个文件复制到 upstream 仓库的如下位置templates/manifest/index.ts templates/manifest/meta.yaml也就是说这个目录本身是模板的模板——既可以直接用于本仓库维护者的 upstream 提交流程其生成逻辑和元数据 Schema 也完整暴露了 Manifest 在 Easypanel 上运行所需的全部环境约束。模板一次预置的能力从 index.ts 可以完整看到使用manifestdotbuild/manifest:6镜像创建 Manifest 应用服务创建 PostgreSQL 16 数据库服务为压缩后的请求录制request recordings挂载持久化应用卷自动生成数据库密码、Better Auth 会话密钥与 Manifest 加密密钥通过 HTTPS 域名代理到应用端口2099。二、模板生成逻辑index.ts 逐行拆解deploy/easypanel/template/index.ts 是模板的核心生成器它接收meta.yaml定义的 Schema 输入输出 Easypanel 可执行的服务清单。其逻辑可分为三部分。1. 随机密钥的生成const databasePassword randomPassword(); const authSecret randomString(64); const encryptionKey randomString(64);三个随机值分别承担不同职责databasePasswordPostgreSQL 服务密码同时被拼进应用的DATABASE_URLauthSecretBetter Auth 的会话签名密钥对应BETTER_AUTH_SECRET64 位随机字符串远超源码要求的最低长度encryptionKeyManifest 的静态加密密钥对应MANIFEST_ENCRYPTION_KEY用于加密存储的 Provider Key 等敏感数据。密钥自动生成是模板的重要价值——手动部署时这一步最容易出错详见第五节。2. 应用服务定义services.push({ type: app, data: { serviceName: input.appServiceName, source: { type: image, image: input.appServiceImage }, domains: [{ host: $(EASYPANEL_DOMAIN), port: 2099 }], env: [ /* ... */ ].join(\n), mounts: [ { type: volume, name: recordings, mountPath: /data/request-recordings, }, ], }, });关键点域名占位符$(EASYPANEL_DOMAIN)由 Easypanel 在部署时替换为项目实际域名代理目标端口固定为2099这与 Dockerfile 中的EXPOSE 2099一致挂载卷recordings指向/data/request-recordings与 Dockerfile 中镜像内置的/data/request-recordings目录路径完全对应保证容器重启后请求录制数据不丢失env使用\n拼接为多行环境变量块这是 Easypanel 模板的标准写法。3. PostgreSQL 服务定义services.push({ type: postgres, data: { serviceName: input.databaseServiceName, image: postgres:16, password: databasePassword, }, });数据库固定使用 PostgreSQL 16 镜像服务名默认manifest-db可由databaseServiceName覆盖密码与上面生成的值一致。三、meta.yaml模板 Schema 与安装指引meta.yaml 定义了模板对外暴露的配置项。Schema 的required字段为appServiceName、appServiceImage、databaseServiceName全部有默认值用户通常无需修改即可部署。配置项类型默认值说明appServiceNamestringmanifest应用服务名appServiceImagestringmanifestdotbuild/manifest:6应用镜像可按需固定其他版本databaseServiceNamestringmanifest-dbPostgreSQL 服务名telemetryDisabledenum0启用0启用匿名遥测1关闭元数据中的instructions给出了两条部署后的关键指引部署完成后打开生成的域名创建第一个管理员账号——全新安装会被重定向到/setup你创建的第一个账号即成为管理员在配置 OAuth 回调 URL 或生产认证流程之前务必使用真实 HTTPS 域名——这直接对应源码中BETTER_AUTH_URL的语义见第四节。changeLog记录了模板迭代历史2026-07-08 首次发布2026-08-06 起将压缩请求录制持久化到独立应用卷。benefits与features则从产品角度总结了模板价值OpenAI 兼容端点、数据路径完全自托管、自带 Provider 接入能力、PostgreSQL 持久化、请求录制持久化与用量追踪。四、模板注入的全部环境变量与源码依据模板通过env块注入了 13 个环境变量它们全部能被 app.config.ts 等后端模块读取。逐项拆解如下PORT2099 BIND_ADDRESS0.0.0.0 DATABASE_URLpostgresql://postgres:password$(PROJECT_NAME)_manifest-db:5432/$(PROJECT_NAME) BETTER_AUTH_SECRET64-char-random MANIFEST_ENCRYPTION_KEY64-char-random BETTER_AUTH_URLhttps://$(PRIMARY_DOMAIN) MANIFEST_MODEselfhosted NODE_ENVproduction SEED_DATAfalse DB_POOL_MAX10 AUTH_DB_POOL_MAX5 REQUEST_RECORDING_STORAGEfilesystem REQUEST_RECORDING_FILESYSTEM_PATH/data/request-recordings MANIFEST_TELEMETRY_DISABLED0PORT2099/BIND_ADDRESS0.0.0.0监听端口与绑定地址。后端在 app.config.ts 中读取PORT默认回退为3001BIND_ADDRESS默认127.0.0.1模板显式覆盖为公网可达的0.0.0.0:2099。DATABASE_URLpostgresql://postgres:password$(PROJECT_NAME)_manifest-db:5432/$(PROJECT_NAME)。其中$(PROJECT_NAME)是 Easypanel 项目级占位符主机名由项目名加服务名构成这是同一 Easypanel 项目内服务间互通的约定格式。DATABASE_URL是必填项缺失时 app.config.ts 会直接抛错。BETTER_AUTH_SECRETBetter Auth 会话签名密钥。源码 auth.instance.ts 明确要求其长度至少 32 字符否则生产环境启动即抛错——模板生成的 64 位随机串完全满足。MANIFEST_ENCRYPTION_KEY静态加密密钥。加密工具 crypto.util.ts 的getEncryptionSecret()优先使用该变量要求 ≥32 字符若未设置则回退到BETTER_AUTH_SECRET并在生产环境打印警告——因为回退意味着一次会话密钥泄露同时危及签名与已存敏感数据。模板生成独立密钥正是为了避免这一风险。BETTER_AUTH_URLhttps://$(PRIMARY_DOMAIN)认证与 MCP 资源的权威来源。源码 auth.instance.ts 基于它推导authIssuer{origin}/api/auth与mcpResource{origin}/api/v1/mcp因此该值必须与用户实际访问的域名完全一致尾斜杠会被规范化去除否则 MCP 客户端会因 resource 与连接 URL 不一致而断开。MANIFEST_MODEselfhosted/NODE_ENVproduction声明自托管模式与生产环境。SEED_DATAfalse关闭演示数据播种避免污染生产库。DB_POOL_MAX10/AUTH_DB_POOL_MAX5应用连接池与认证连接池上限。源码 app.config.ts 注释指出单进程连接池默认保持保守默认 10多副本部署会成倍放大该值过大连接池可能榨干 PostgreSQL 的max_connections并诱发内存型查询开销auth.instance.ts 则为 Better Auth 单独建池默认上限 5空闲连接 30 秒回收避免两个连接池合力耗尽数据库连接。REQUEST_RECORDING_STORAGEfilesystem/REQUEST_RECORDING_FILESYSTEM_PATH/data/request-recordings请求录制存储后端与路径。存储解析逻辑见 request-recording-storage.service.ts默认值为auto能力探测显式指定filesystem则强制使用本地文件系统生产环境下文件系统默认路径恰好是/data/request-recordings与模板的挂载点、Dockerfile 中预建的目录一致。文件系统后端会把录制对象写入root/request-recordings/v1/tenants/tenant/requests/request/attempts/attempt.json.gz见同一文件的objectKey方法路径段做了 URL 编码与路径穿越防护。MANIFEST_TELEMETRY_DISABLED0匿名遥测开关。1关闭、0启用直接透传自meta.yaml的telemetryDisabled选项。值得一提的是/data/request-recordings的目录约定在 Dockerfile 中被固化镜像构建阶段会预先创建该目录并交给nonroot用户同时 Dockerfile 内置了基于/api/v1/health的HEALTHCHECK每 30 秒一次45 秒启动宽限Easypanel 可以据此感知容器健康状态。五、两种部署路径路径 A模板部署推荐当 Manifest 已进入你的 Easypanel 模板目录时打开你的 Easypanel 项目选择Templates搜索Manifest除非需要固定其他版本否则保留默认镜像manifestdotbuild/manifest:6部署模板。模板会自动完成第四节描述的全部预置应用服务、PostgreSQL、持久化录制卷、生成的密钥、2099端口的 HTTPS 域名代理。部署后打开生成的域名全新安装会重定向到/setup创建的第一个账号即管理员。路径 B手动部署在模板被 upstream 收录之前可以按 TUTORIAL.md 手动创建服务步骤与本模板生成的内容完全等价。创建 PostgreSQL 服务打开项目 →Create Service→Postgres→ 命名manifest-db→ 生成并保存强密码。创建 Manifest 应用服务Create Service→App→ 源类型选Docker image→ 镜像manifestdotbuild/manifest:6→ 代理端口设为2099→ 添加域名并标记为主域名。设置环境变量与前文模板注入的变量一致PORT2099 BIND_ADDRESS0.0.0.0 DATABASE_URLpostgresql://postgres:postgres-password$(PROJECT_NAME)_manifest-db:5432/$(PROJECT_NAME) BETTER_AUTH_SECRETopenssl-rand-hex-32 MANIFEST_ENCRYPTION_KEYdifferent-openssl-rand-hex-32 BETTER_AUTH_URLhttps://$(PRIMARY_DOMAIN) MANIFEST_MODEselfhosted NODE_ENVproduction SEED_DATAfalse DB_POOL_MAX10 AUTH_DB_POOL_MAX5 REQUEST_RECORDING_STORAGEfilesystem REQUEST_RECORDING_FILESYSTEM_PATH/data/request-recordings MANIFEST_TELEMETRY_DISABLED0在本地生成两个互不相同的密钥openssl rand -hex 32 openssl rand -hex 32密码编码注意事项DATABASE_URL中的 PostgreSQL 密码请使用字母数字或十六进制。如果密码包含 URL 保留字符如、:、/、%、#必须先行百分号编码再拼入连接串否则连接解析会出错。最后添加一个名为recordings的应用卷挂载到/data/request-recordings然后部署应用。六、部署验证与首启冒烟流程打开 Easypanel 域名后先用健康检查接口确认后端存活curl -fsS https://your-easypanel-domain/api/v1/health返回 OK 即表示应用可服务。向 upstream 提交模板前TUTORIAL.md 建议对完整首启流程做一次冒烟测试确认应用启动无崩溃循环确认 PostgreSQL 迁移执行完成确认/api/v1/health返回 OK在 Easypanel 域名上打开/setup创建第一个管理员账号在同一域名上登出再登入重启应用并确认账号仍然存在。其中重启后账号仍存在验证的是 PostgreSQL 持久化与密钥一致性——如果BETTER_AUTH_SECRET在重启后变化会话将无法解密而模板生成的密钥是持久化存储的天然规避了该问题。七、生产环境注意事项综合 TUTORIAL.md 与源码生产部署需重点关注备份通过 Easypanel 或服务器提供商定期备份 PostgreSQL 服务请求录制卷建议一并纳入备份策略HTTPS 域名启用 OAuth Provider 之前必须使用真实 HTTPS 域名——BETTER_AUTH_URL同时参与 issuer 推导与 MCP 资源标识使用临时/非 HTTPS 域名会导致回调或 MCP 连接失败密钥分离保持BETTER_AUTH_SECRET与MANIFEST_ENCRYPTION_KEY为两个独立值。若共用crypto.util.ts 会警告一次会话密钥泄露即同时危及会话签名与已存 Provider/OAuth 密钥遥测设置MANIFEST_TELEMETRY_DISABLED1可关闭匿名自托管遥测默认启用多副本如果部署超过一个 Manifest 副本应调低数据库连接池大小或提升 PostgreSQL 连接容量——DB_POOL_MAX与AUTH_DB_POOL_MAX会在多进程场景下成倍放大总连接数可能榨干数据库的max_connections。八、小结Easypanel 模板目录是 Manifest 自托管部署的最简入口index.ts 把镜像 PostgreSQL 16 持久化录制卷 三个随机密钥 2099 端口域名代理固化为可复现的部署单元meta.yaml 则把安装指引、配置 Schema 与产品特性一并打包。无论你是通过模板一键部署还是按 TUTORIAL.md 手动搭建理解这些环境变量与底层源码的对应关系都是排障、升级与安全加固的基础。后续如需接入 OAuth、调整请求录制保留策略或扩展自定义 Provider可继续阅读仓库中的 部署文档汇总、app.config.ts 与 request-recording-storage.service.ts 获取更底层的配置面。【免费下载链接】llm-gatewayConnect Your Agents And Harnesses With Any Provider 项目地址: https://gitcode.com/GitHub_Trending/manifest7/llm-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考