Paperless-ngx 怎么为 Gmail 和 Outlook 邮件账户配置 OAuth2 认证【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx如果你的邮件账户无法再使用 App Password 登录Gmail、Outlook 这类账户常见或你希望改用更规范的认证方式可以把 Paperless-ngx 的邮件账户配置成 OAuth2 认证。Paperless-ngx 原生支持 Gmail 和 Outlook 两种 OAuth2 邮件账户在 Google/Microsoft 开发者平台创建应用拿到凭据、在 Paperless 侧配置几个环境变量后直接在邮件设置页点击 OAuth 入口完成授权之后邮件拉取和令牌刷新都会自动进行。适用前提已有一个可访问的 Paperless-ngx 实例Web 界面可登录拥有 Google 或 Microsoft 账户并且有权在该提供商的控制台创建开发者应用拿到 client ID 与 client secret。配置前需要准备的东西官方文档明确说明在 Google 或 Microsoft 处创建所需开发者应用的具体步骤不在本文档范围内项目维护的文档指向其 wiki 的 Email OAuth App Setup 页面见 usage.md 的 OAuth Email Setup 一节。拿到 client ID / client secret 并正确注册回调地址后才能进入下面的 Paperless 侧配置。Paperless 侧需要设置的配置变量定义见 configuration.md 的 Email OAuth 一节变量用途PAPERLESS_GMAIL_OAUTH_CLIENT_IDGmail OAuth 的 client IDGmail OAuth 设置必填PAPERLESS_GMAIL_OAUTH_CLIENT_SECRETGmail OAuth 的 client secretGmail OAuth 设置必填PAPERLESS_OUTLOOK_OAUTH_CLIENT_IDOutlook OAuth 的 client IDOutlook OAuth 设置必填PAPERLESS_OUTLOOK_OAUTH_CLIENT_SECRETOutlook OAuth 的 client secretOutlook OAuth 设置必填PAPERLESS_OAUTH_CALLBACK_BASE_URLOAuth 回调的基础 URL应为 Paperless 实例可被访问到的 URL规则是只用 Gmail 就只配 Gmail 两项只用 Outlook 就只配 Outlook 两项。PAPERLESS_OAUTH_CALLBACK_BASE_URL未设置时回退使用PAPERLESS_URL但两者至少必须有一个否则 OAuth 邮件设置无法启用。注意该回调设置只作用于邮件 OAuth与 SSO 登录设置无关。另外注意PAPERLESS_URL本身的格式限制见 configuration.md不要带尾部斜杠且值中不能包含路径例如domain.com/path即使你是在子路径下安装 Paperless。在部署环境中写入配置以仓库自带的 Docker Compose 部署为例环境变量写在部署目录的docker/compose/docker-compose.env中该文件本身不含 OAuth 变量需要自行添加并取消对应行的注释规则。将...替换为你在提供商控制台实际拿到的值# 以下 ... 占位符请替换为你在 Google/Microsoft 控制台创建应用后拿到的真实值 PAPERLESS_GMAIL_OAUTH_CLIENT_ID你的 Gmail client ID PAPERLESS_GMAIL_OAUTH_CLIENT_SECRET你的 Gmail client secret # 如果你用的是 Outlook 账户则改为下面两个变量或两组都配以同时支持两种账户 #PAPERLESS_OUTLOOK_OAUTH_CLIENT_ID你的 Outlook client ID #PAPERLESS_OUTLOOK_OAUTH_CLIENT_SECRET你的 Outlook client secret # OAuth 回调基础 URLPaperless 实例可被访问到的地址。 # 若不设置此项则回退使用 PAPERLESS_URL两者至少设置其一。 PAPERLESS_OAUTH_CALLBACK_BASE_URLhttps://paperless.example.com其中https://paperless.example.com沿用了仓库 docker-compose.env 中PAPERLESS_URL的示例地址写法请替换为你的实际实例地址且不带尾部斜杠、不含路径。写入后重启 Docker Compose 服务使环境变量生效具体 compose 文件以你部署时使用的为准仓库提供了 docker/compose/docker-compose.yml 下的多个变体。在 Web 界面添加 OAuth 邮件账户环境变量生效后操作路径是纯界面操作打开邮件设置页前端路由/settings/mail即管理列表中的 Mail 部分。新增邮件账户选择 Gmail 或 Outlook 并使用 OAuth2 授权。账户列表界面会分别显示 Google / Microsoft 图标标识对应类型的账户前端实现见 mail.component.ts。按提示完成浏览器内的授权。授权成功后页面会显示 OAuth2 authentication success 提示失败时显示 OAuth2 authentication failed, see logs for details此时查看 Paperless 日志定位原因。授权完成后会出现新建的账户需要你填入该账户的邮箱地址并保存。保存后这个账户就和普通邮件账户一样工作后续为它定义邮件规则folder、过滤器、动作等拉取到的附件会按规则被消费进文档库。令牌刷新由 Paperless 自动处理不需要手工维护。验证配置是否生效文档给出的判断点按顺序是OAuth 授权回跳结果回到邮件设置页时出现 OAuth2 authentication success 提示说明回调 URL 与 client 凭据都正确出现 failed 提示则检查PAPERLESS_OAUTH_CALLBACK_BASE_URL/PAPERLESS_URL是否与浏览器实际访问的地址一致以及提供商侧登记的回调地址是否一致。账户能正常拉取邮件Paperless 默认每 10 分钟自动拉取一次邮件周期可用PAPERLESS_EMAIL_TASK_CRON调整见 usage.md。也可以手动触发一次立即看到效果。手动触发的mail_fetcher管理命令不带参数会处理所有邮件账户和规则见 administration.md Fetching e-mail 一节# Docker Compose 部署paperless 运行中/path/to/paperless 替换为你的部署目录 $ cd /path/to/paperless $ docker compose exec webserver mail_fetcher裸机部署则为cd /path/to/paperless/src python3 manage.py mail_fetcher可能需要sudo -Hu paperless_user。令牌刷新配置成功后无需人工干预如果某次刷新失败日志中会出现Failed to refresh oauth token for account ...错误实现见 oauth.py这通常意味着访问令牌已过期且刷新令牌失效需要重新走一次 OAuth 授权。限制与注意事项PAPERLESS_OAUTH_CALLBACK_BASE_URL未设置且PAPERLESS_URL也未设置时OAuth 邮件设置不生效这是启用前置条件不是可选优化。PAPERLESS_OAUTH_CALLBACK_BASE_URL只影响邮件 OAuth不要拿它去改 SSO 登录的回调行为。PAPERLESS_URL不能带路径如果你的实例挂在子路径下需要仔细核对回调可达性。邮件账户连接时若 IMAP 主机名解析到内网地址PAPERLESS_EMAIL_ALLOW_INTERNAL_HOSTS为false会阻止连接默认true见 configuration.mdGmail/Outlook 这类公网服务一般不受影响自建内网邮箱要留意。文档没有给出 Gmail/Outlook 侧应用创建的字段级说明如所需 API、权限范围、回调 URL 的具体填法这部分以提供商控制台和官方 wiki 指引为准本文不展开。【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考