Documenso 自托管环境下的反向代理配置指南

问题背景

在自托管Documenso电子签名服务时，许多用户遇到了一个常见问题：当通过反向代理访问服务时，登录后系统会将用户从配置的公开域名（如https://documenso.my.domain）重定向到本地地址（http://localhost:3000），导致出现"Error: No session found"错误。这种情况通常发生在使用Docker容器部署Documenso并通过Nginx等反向代理对外提供服务的环境中。

问题根源分析

这个问题的根本原因在于Documenso的认证系统配置不完整。Documenso基于Next.js框架构建，使用NextAuth.js处理认证流程。NextAuth.js需要一个明确的NEXTAUTH_URL环境变量来正确处理会话管理和重定向逻辑。

在自托管环境中，如果没有正确配置以下三个关键环境变量，就会出现重定向问题：

1. NEXT_PUBLIC_WEBAPP_URL - 指定用户访问的前端公开URL
2. NEXTAUTH_URL - NextAuth.js用于构建回调URL的基础URL
3. NEXT_PRIVATE_INTERNAL_WEBAPP_URL - 容器内部通信使用的URL

完整解决方案

Docker Compose配置

在Docker Compose文件中，需要确保正确传递所有必要的环境变量。以下是关键部分的配置示例：

environment:
  - PORT=3000
  - NEXT_PUBLIC_WEBAPP_URL=${NEXT_PUBLIC_WEBAPP_URL:?err}
  - NEXTAUTH_URL=${NEXTAUTH_URL:-http://localhost:$PORT}
  - NEXT_PRIVATE_INTERNAL_WEBAPP_URL=${NEXT_PRIVATE_INTERNAL_WEBAPP_URL:-http://localhost:$PORT}

环境变量文件(.env)配置

在.env文件中，需要设置以下关键变量：

NEXT_PUBLIC_WEBAPP_URL=https://documenso.my.domain
NEXTAUTH_URL=https://documenso.my.domain
NEXT_PRIVATE_INTERNAL_WEBAPP_URL=http://documenso:3000

配置说明

1. NEXT_PUBLIC_WEBAPP_URL
   这个变量指定了用户访问Documenso的公开URL，必须以https://开头（如果使用了SSL），并且不能以斜杠结尾。

2. NEXTAUTH_URL
   这个变量必须与NEXT_PUBLIC_WEBAPP_URL相同，它告诉NextAuth.js在构建回调URL时使用哪个基础URL。这是解决重定向问题的关键变量。

3. NEXT_PRIVATE_INTERNAL_WEBAPP_URL
   这个变量用于容器内部通信，应该指向Documenso容器的内部名称和端口（如http://documenso:3000）。

常见错误排查

1. 变量未传递到容器
   生产环境，建议考虑以下额外配置：

2. 使用独立的数据库容器