如何为 Budibase 单镜像中的 LiteLLM 组件配置外部 Postgres 数据库

如何为 Budibase 单镜像中的 LiteLLM 组件配置外部 Postgres 数据库【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibaseBudibase 的 single image 部署方式会把 MinIO、CouchDB、Redis、LiteLLM 等所有组件打进同一个容器构建脚本在 hosting/single/Dockerfile操作说明在 hosting/single/README.md。这个镜像中的 LiteLLM 默认以store_model_in_db: true运行见 hosting/litellm_config.yaml因此必须有一个 Postgres 数据库存放模型等元数据。不配置时容器会自行启动一个内部 Postgres数据落在${DATA_DIR}/litellm/postgres。本文的任务是让你自己准备一个外部 Postgres 实例并让 single image 中的 LiteLLM 组件使用它而不是使用内部实例。默认行为与切换开关先理解 hosting/single/runner.sh 的判定逻辑配置才有依据未设置LITELLM_INTERNAL_DB时如果设置了DATABASE_URLrunner 会自行把LITELLM_INTERNAL_DB置为false否则置为true启动内部 Postgres。LITELLM_INTERNAL_DBtrue且未提供DATABASE_URL时runner 会拼装一个指向127.0.0.1的内部连接串格式为postgresql://${LITELLM_DB_USER}:${LITELLM_DB_PASSWORD}127.0.0.1:${LITELLM_DB_PORT}/${LITELLM_DB_NAME}其中变量默认值为LITELLM_DB_NAMElitellm、LITELLM_DB_USERllmproxy、LITELLM_DB_PORT5432。LITELLM_INTERNAL_DBfalse且DATABASE_URL为空时runner 直接报错退出日志为LiteLLM requires DATABASE_URL. Set DATABASE_URL or keep LITELLM_INTERNAL_DBtrue.容器起不来。hosting/single/README.md 给出的外部 Postgres 切换方式就是设置两个环境变量DATABASE_URL外部 Postgres 的连接串格式参照上面 runner 内部拼装的postgresql://用户:密码主机:端口/数据库名把主机换成容器能访问到的外部地址LITELLM_INTERNAL_DBfalse显式关闭内部 Postgres。另外注意LITELLM_MASTER_KEY和LITELLM_SALT_KEY是 LiteLLM 启动的硬性要求缺失时 runner 会报错退出但如果你不提供runner 会用uuidgen随机生成并持久化到${DATA_DIR}/.env所以这不是阻断项。准备条件一台满足构建要求的机器文档建议在 6GB 内存、20GB 可用磁盘的环境下构建构建产物镜像约 2GB。构建流程在 Debian 11 和 AlmaLinux 8 上验证过其他发行版需要自行调整命令。一个已经建好的外部 Postgres 实例容器内能访问到它的主机与端口。你需要拿到连接串所需的用户、密码、数据库名。文档没有对外部实例的 Postgres 版本提出要求只要求 LiteLLM 能通过DATABASE_URL连上它。按 hosting/single/README.md 安装 Node16、yarn、lerna 和 Dockercurl -sL https://deb.nodesource.com/setup_16.x | sudo bash - apt install -y nodejs node -v npm install -g yarn jest lerna apt install -y docker.io文档记录的已测版本组合为 Docker 22.11.0、node 16.15.1、yarn 1.22.19、lerna 5.1.4。配置外部 Postgres两种配置位置任选其一也可以两者结合方式一写入 DockerfileREADME 的推荐做法README 的 “Amend Environment Variables” 一节要求编辑hosting/single/Dockerfile把环境变量改掉再构建。在 hosting/single/Dockerfile 中添加两行ENVENV DATABASE_URLpostgresql://${DB_USER}:${DB_PASSWORD}${EXTERNAL_HOST}:${EXTERNAL_PORT}/${DB_NAME} ENV LITELLM_INTERNAL_DBfalse${DB_USER}、${DB_PASSWORD}、${EXTERNAL_HOST}、${EXTERNAL_PORT}、${DB_NAME}均替换为你外部 Postgres 实例的实际值其中${EXTERNAL_HOST}:${EXTERNAL_PORT}必须是容器运行时能够路由到的地址。方式二运行时通过 docker run 传入runner.sh 有一段明确注释 “Preserve runtime LiteLLM DB settings so they are not overridden by persisted .env values”启动时传入的DATABASE_URL和LITELLM_INTERNAL_DB会覆盖${DATA_DIR}/.env中持久化的旧值并在启动结束时回写到.env。所以不重新构建镜像也能切换外部数据库docker run -d -p 80:80 -p 443:443 --name budibase \ -e DATABASE_URLpostgresql://${DB_USER}:${DB_PASSWORD}${EXTERNAL_HOST}:${EXTERNAL_PORT}/${DB_NAME} \ -e LITELLM_INTERNAL_DBfalse \ budibase:latest替换方式同上。如果容器${DATA_DIR}/.env容器内即/data/.env里已经有旧的DATABASE_URL用这种方式传入的新值会优先生效。构建并启动以下命令都在 Budibase 仓库根目录执行完整顺序来自 README 的 “Build the Image” 与 “Run the Container” 两节node ./hosting/scripts/setup.js yarn yarn build yarn build:docker:singleyarn build:docker:single会做准备工作并执行 docker build。如果 docker build 步骤失败README 给出手动重跑方式docker build --build-arg TARGETARCHamd --no-cache -t budibase:latest -f ./hosting/single/Dockerfile .启动容器方式一配置后可直接用 README 原始命令docker run -d -p 80:80 -p 443:443 --name budibase budibase:latest两个可选调整需要自定义域名时按 README 说明设置CUSTOM_DOMAIN并要求该域名的 DNS 指向容器所在公网 IP否则 LetsEncrypt 证书申请会失败如果前面已有反向代理可以省略CUSTOM_DOMAIN并把流量指向 80 端口。宿主机 80 端口被占用时可改用-p 8080:80之类的映射。生产环境还有一个数据持久化前提runner.sh 在${DATA_DIR}/.env不存在时会生成一批新密钥并打印大段警告——如果DATA_DIR不是持久卷每次容器重启都会重新生成密钥导致所有用户掉线Session not found/ 403。文档要求在投入生产前为${DATA_DIR}挂载持久卷docker -v或 k8s PVC并可用BUDIBASE_ACK_EPHEMERAL_DATA1关闭该警告。验证结果按 README 的 “Check” 一节查看容器状态与健康检查docker ps docker logs budibase在日志中确认 LiteLLM 的启动结论。runner 等待 LiteLLM 就绪默认超时LITELLM_READY_TIMEOUT_SECONDS120秒后打印以下之一LiteLLM is ready.LiteLLM 正常Timed out waiting for LiteLLM readiness after ${litellm_ready_timeout}s. Continuing startup without waiting further.以及LiteLLM is not ready yet. App and worker will still start.LiteLLM 未在超时内就绪但 app 和 worker 照常启动。LiteLLM 的就绪判定是http://localhost:4000/health/liveliness返回 200runner 内部探测使用的就是这个端点容器内执行即可。hosting/single/Dockerfile 中EXPOSE 4000注释标明 4000 端口是 LiteLLM config dashboard如果需要从宿主机直接访问 dashboard在docker run时追加-p 4000:4000即可。健康检查脚本 hosting/single/healthcheck.sh 把 LiteLLM 当作可选组件4000 端口的 liveliness 不是 200 时只打印WARNING: LiteLLM is not running, AI features are unavailable不会把容器判为不健康。WARNING: LiteLLM Postgres is down这一条只在LITELLM_INTERNAL_DBtrue时才会触发——配置外部 Postgres 后该检查自动跳过属于预期行为。排查与限制外部数据库连不上时文档没有给出专门的报错分支能依据的仍是上面的通用路径docker logs budibase中的就绪/超时日志、docker ps的健康状态以及 4000 端点是否返回 200。LiteLLM 未就绪不会阻塞 app 和 worker 启动影响的是 AI 功能不可用。runner 在启动 LiteLLM 前会导出USE_PRISMA_MIGRATETrueDockerfile 中也安装了 prisma 并用 LiteLLM 自带的proxy/schema.prisma执行prisma generate说明容器会对连接到的 Postgres 执行 LiteLLM 的 schema 迁移数据库由 LiteLLM 组件自行管理。镜像中 LiteLLM 的版本由构建参数LITELLM_PYPI_VERSION控制当前 hosting/single/Dockerfile 默认值为1.83.10安装的是litellm[proxy]运行在/opt/venv/litellm独立虚拟环境中。LiteLLM 配置文件默认使用/litellm/config.yaml由 hosting/litellm_config.yaml 复制而来其中store_model_in_db: true决定了 Postgres 是必需的如果你在自己的${DATA_DIR}/litellm/config.yaml挂载了配置runner 会优先使用挂载版本并打印Using user-mounted litellm config。本文只覆盖 single image 中 LiteLLM 的外部数据库配置宿主机安装 Node/Docker 的具体细节以 README 为准其他发行版需要自行调整。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考