SolidTime自托管部署中的用户注册问题解决方案

问题背景

在SolidTime时间跟踪系统的自托管部署过程中，部分用户反馈在全新安装后遇到无法注册新账户的问题。具体表现为：注册表单提交后密码字段被清空，但系统未创建新用户，且数据库表显示为空状态。

环境分析

典型问题环境通常具有以下特征：

• 基于Debian 12操作系统
• 使用Docker容器化部署
• 通过8000端口访问Web界面
• 数据库迁移显示已完成（无待迁移项）

核心问题诊断

经过技术分析，该问题主要由两个关键配置因素导致：

1. HTTPS配置冲突：当系统在非HTTPS环境下运行时（如本地测试或内部网络部署），Laravel框架默认的安全Cookie设置会导致会话验证失败。

2. 邮件验证缺失：系统默认需要邮件验证，但在初始配置中若未正确设置邮件服务，会导致用户注册流程无法完成。

解决方案

配置修正

在laravel.env配置文件中添加以下关键参数：

SESSION_SECURE_COOKIE=false

此设置明确告知系统允许在非HTTPS连接下使用会话Cookie，解决表单提交后的会话保持问题。

用户验证处理

对于初始管理员账户，可通过命令行工具手动验证：

docker compose exec scheduler php artisan admin:user:verify [e-mail]

最佳实践建议

1. 环境规划：

   • 生产环境建议配置有效的HTTPS证书
   • 开发环境可保持HTTP但需相应调整安全设置

2. 部署检查清单：

   • 验证数据库连接配置
   • 检查会话存储设置
   • 确认邮件服务配置（或准备手动验证方案）

3. 故障排查步骤：

   • 检查Docker容器日志
   • 验证数据库表结构
   • 测试基础API端点响应

技术原理

该问题涉及Laravel框架的安全机制设计：

• 安全Cookie（Secure Cookie）是防止中间人攻击的重要措施
• 在HTTPS环境下自动加密Cookie内容
• HTTP环境下需要显式禁用该特性才能保证功能正常

后续改进

建议在项目文档中明确以下内容：

• 不同环境下的安全配置要求
• 无邮件服务时的替代验证方案
• 常见部署问题的排查指南

通过以上措施，可以确保SolidTime系统在各种部署环境下都能正常完成用户注册流程，为团队协作提供可靠的时间跟踪解决方案。