Pixelfed项目Docker部署中Passport密钥生成问题解析

在使用Docker部署Pixelfed社交平台时，开发者可能会遇到一个常见问题：Passport OAuth密钥未自动生成，导致系统出现"Invalid key supplied"错误。本文将深入分析该问题的成因及解决方案。

问题现象

当通过Docker-compose完成Pixelfed部署后，访问时间线功能时系统抛出异常，错误信息指向league/oauth2-server组件的CryptKey.php文件，提示提供的密钥无效。检查发现storage/oauth-private.key和storage/oauth-public.key这两个Passport所需的密钥文件缺失。

根本原因

Pixelfed的Docker部署流程中，正常情况下应通过11-first-time-setup初始化脚本自动完成Passport密钥的生成。该脚本的执行依赖于两个关键环境变量：

1. OAUTH_ENABLED：控制OAuth功能开关，必须设为true
2. DOCKER_APP_RUN_ONE_TIME_SETUP_TASKS：控制首次安装任务执行，必须设为1

若这两个条件不满足，或初始化脚本被手动禁用，就会导致Passport密钥生成步骤被跳过。

解决方案

方案一：检查环境变量配置

确保docker-compose.yml或.env配置文件中包含以下设置：

environment:
  OAUTH_ENABLED: "true"
  DOCKER_APP_RUN_ONE_TIME_SETUP_TASKS: "1"

方案二：手动执行密钥生成

如果初始化过程已完成但密钥缺失，可进入容器手动执行：

docker-compose exec app php artisan passport:install

此命令会生成所需的RSA密钥对并存储在storage目录下。

技术背景

Pixelfed使用Laravel Passport实现OAuth2认证，该组件依赖RSA密钥对来保证令牌的安全性。在Docker化部署中，密钥生成应作为初始化流程的一部分自动完成。开发者在排查此类问题时，应优先检查：

1. 容器日志中是否有初始化脚本的执行记录
2. 环境变量是否被正确传递到容器内部
3. storage目录的写入权限是否正常

通过理解这一机制，开发者可以更有效地诊断和解决Pixelfed部署过程中的认证相关问题。