feat: encode special characters in database connection string to prevent prisma errors

问题场景

用户使用 docker pull langfuse/langfuse:2 拉取镜像后，通过以下方式启动自托管 Langfuse：

docker run --name langfuse --env-file .env -p 3000:3000 langfuse/langfuse

容器启动时加载 Prisma schema 并尝试应用数据库迁移，随后迁移失败、容器退出。用户的 DATABASE_URL 指向 AWS RDS 上的 PostgreSQL 数据库，但用户名/密码只有字母和数字。

报错原文

Error: P1013

The provided database string is invalid. The scheme is not recognized in database URL. Please refer to the documentation in https://www.prisma.io/docs/reference/database-reference/connection-urls for constructing a correct connection string. In some cases, certain characters must be escaped. Please check the string for any illegal characters.

Prisma schema loaded from packages/shared/prisma/schema.prisma
Datasource "db": PostgreSQL database

Error: P1013: The provided database string is invalid. The scheme is not recognized in database URL. Please refer to the documentation in https://www.prisma.io/docs/reference/database-reference/connection-urls for constructing a correct connection string. In some cases, certain characters must be escaped. Please check the string for any illegal characters.
Applying database migrations failed. This is mostly caused by the database being unavailable.
Exiting...

原因分析

最可能的原因：DATABASE_URL 中含有 Prisma 无法正确解析的字符，导致它认为 URL 的 scheme 无效。Issue 讨论中确认的相关因素有：

• 用户名或密码含特殊字符时，需要按 Prisma 文档做 URL 编码；未编码的字符可能使 URL 解析出错。原报告者已自查用户名和密码仅含字母和数字，因此该因素对其不成立。
• 另一个可能原因：.env 中 DATABASE_URL 使用了双引号包裹。维护者提出去掉双引号进行测试，但原报告中未给出该操作后的确认结果，故只能作为可优先尝试方向。

环境排查

• 确认镜像版本：Issue 使用 langfuse/langfuse:2。
• 确认启动方式：docker run --env-file .env，检查容器实际收到的环境变量值。
• 确认 DATABASE_URL 的完整格式，例如 postgresql://username:password@host:port/database。
• 确认数据库用户名和密码中是否含特殊字符（含 @ : / ? # % 等）。
• 确认 DATABASE_URL 当前是否已经做过 URL 编码，避免重复编码。
• PostgreSQL 版本及 Prisma 具体版本在 Issue 中未明确，可作为补充排查项。

解决步骤

1. 打开 .env，核对 DATABASE_URL 是否为 postgresql://用户名:密码@主机:端口/库名 这类标准格式，排除多余空格、换行或引号拼接造成的值污染。
2. 可优先尝试：如果 DATABASE_URL 的值外面有双引号，去掉双引号后重新启动容器，观察是否仍触发 P1013。
3. 若用户名或密码含特殊字符，按 Prisma 官方文档“Special characters”一节进行 URL 编码（例如把对应字符替换为 %XX 形式）。
4. 若此前已手动编码过，不要再重复编码；修改后重新执行 docker run，让容器重新执行数据库迁移。
5. 如仍无法解决，可参考 Issue 评论区中提到的相似 Issue #3126 继续排查。

验证方法

重新启动容器后，日志应不再出现 Error: P1013 和 Applying database migrations failed，Prisma 迁移正常执行，容器保持运行并能通过 3000 端口访问 Langfuse 页面。

参考来源

langfuse/langfuse #3923

相关引用：Prisma Connection URLs – Special characters；Docker run – env；langfuse/langfuse #3126

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。