时光邮局 — Time Letter

给未来的自己或他人写信，在指定时间通过邮件自动发送。
版本： v1.0.0 | 发布日期： 2026年7月

目录

• 一、项目简介
• 二、功能概览
• 三、技术栈与运行环境
• 四、安装前准备
• 五、安装步骤详解
• 六、安装后必要配置
• 七、管理后台使用指南
• 八、定时任务详解
• 九、常见问题排查

一、项目简介

时光邮局是一个可以独立部署在你自己服务器上的信件投递平台。用户在线撰写信件，设定未来某个日期，系统会在指定时间自动将信件以邮件形式发送到收件人邮箱。

核心场景：

• 给一年后的自己写一封信
• 给朋友/家人在特殊日期发送祝福
• 建立公开信件墙，分享故事与感悟
• 作为企业/社区的纪念日营销工具

架构说明： 本项目需连接授权服务器进行许可证验证和版本更新。

二、功能概览

2.1 用户功能

2.2 管理后台功能

2.3 系统特性

• PC/Mobile 双端物理隔离：自动检测设备类型，加载独立的 CSS 和组件
• 内容审核体系：敏感词库 + 信誉分机制（≥80 分自动过审）
• 自动更新：后台一键检查并更新到最新版本
• 维护模式：支持手动/定时开启，包含倒计时恢复页面
• 速率限制：登录、注册、发信等关键操作内置频率限制
• Redis 缓存：可选启用 Redis 提升性能

三、技术栈与运行环境

3.1 技术栈

3.2 服务器最低配置

3.3 必需 PHP 扩展

四、安装前准备

4.1 你需要准备

1. 一台服务器（VPS 或云服务器），推荐安装 Debian 12 系统
2. 宝塔面板 已安装在服务器上（如未安装，访问 bt.cn 查看教程）
3. 一个域名（如 yourdomain.com），已解析到服务器 IP
4. SSL 证书（推荐，宝塔可一键申请免费 Let's Encrypt 证书）

4.2 环境确认清单

五、安装步骤详解（共 5 步）

以下步骤请严格按顺序操作，不要跳过任何一步。

第一步：在宝塔中创建网站站点

1. 登录宝塔面板（浏览器访问 http://你的服务器IP:8888）

2. 左侧菜单点击 网站 → 左上角 添加站点

3. 填写站点信息：

   字段	填写内容
   域名	你的域名（如 yourdomain.com）
   PHP 版本	PHP-81
   数据库	选择 MySQL，勾选"自动创建数据库"

4. 点击 提交

创建后请记下以下信息（后续步骤需要）：

数据库名：        ____________
数据库用户名：    ____________
数据库密码：      ____________
站点根目录：      /www/wwwroot/你的域名/

忘记可在宝塔 → 数据库 中查看。

第二步：安装 PHP 必需扩展

1. 宝塔 → 软件商店 → 找到 PHP-8.1 → 点击 设置

2. 选择 安装扩展 标签

3. 确认以下扩展均已安装（绿色即已安装，未安装的点安装）：

   • pdo_mysql — 数据库连接
   • gd — 验证码/图片处理
   • fileinfo — 文件类型检测
   • mbstring — 多字节字符串
   • openssl — 加密通信
   • curl — 远程请求
   • zip — 压缩包处理

4. 安装完成后，在 配置修改 标签中确认上传限制：

   upload_max_filesize = 50M
   post_max_size = 50M

   修改后点击保存，并重启 PHP。

第三步：上传项目文件

1. 宝塔 → 文件 → 进入站点根目录（/www/wwwroot/你的域名/）
2. 上传项目压缩包并解压（确保文件直接在根目录下）

重要检查： 解压后，index.php、install.php 等文件应在 /www/wwwroot/你的域名/ 下，而不是子文件夹中。项目已内置 PHPMailer，无需额外安装 Composer 依赖。

第四步：浏览器完成安装向导

1. 浏览器访问：http://你的域名/install.php

2. 按向导完成安装：

   Step 0 — 环境检测

   • 自动检查 PHP 版本、扩展、目录权限
   • 全部绿色 ✔ 通过后点击下一步

   Step 1 — 授权连接

   • 系统自动申请 API Key，全程自动完成

   Step 2 — 数据库配置

   • 填写第一步记下的数据库名、用户名、密码
   • 主机填 127.0.0.1

   Step 3 — 管理员账户

   • 设置管理员邮箱和登录密码

   Step 4 — 执行安装

   • 自动创建数据库表、写入默认配置
   • 生成 .env 和 installed.lock 文件

   Step 5 — 完成

   • 显示安装报告，提供后台入口

第五步：安装后安全检查

1. 删除安装文件： 宝塔 → 文件 → 找到 install.php → 右键删除
2. 设置目录权限：

# SSH 终端执行
chmod -R 755 /www/wwwroot/你的域名
chown -R www:www /www/wwwroot/你的域名
chmod 777 /www/wwwroot/你的域名/uploads
chmod 777 /www/wwwroot/你的域名/logs
chmod 777 /www/wwwroot/你的域名/runtime

六、安装后必要配置

6.1 配置邮件发送（SMTP）

不配置此项，所有信件无法发送。

1. 登录后台 → 系统设置 → 邮件配置
2. 填写 SMTP 信息：

以 QQ 邮箱 为例：

获取 QQ 邮箱授权码： QQ 邮箱 → 设置 → 账户 → POP3/IMAP/SMTP服务 → 生成授权码 → 按短信提示操作 → 获取 16 位授权码。

其他邮箱参考：

配置完成后，点击 测试发送 验证配置是否生效。

6.2 配置定时任务（Cron）

不配置此项，信件不会自动发送。

系统只需 1 个计划任务，每 1 分钟执行一次，自动完成信件投递和系统自检。

宝塔面板设置方法：

1. 宝塔 → 计划任务 → 添加任务

2. 填写：

   字段	值
   任务类型	Shell 脚本
   任务名称	时光邮局定时任务
   执行周期	N 分钟 → 填 1
   脚本内容	见下方

/www/server/php/81/bin/php /www/wwwroot/你的域名/cron/run.php >> /www/wwwroot/你的域名/logs/cron.log 2>&1

3. 点击确定保存后，可点击 执行 手动测试一次。

6.3 设置站点信息（建议）

1. 后台 → 系统设置 → 站点信息
2. 建议配置网站名称、网站描述和关键词（影响 SEO 和浏览器标签显示）。

6.4 伪静态配置（可选，付费功能）

项目默认使用 ?page= 参数路由，无需额外配置即可正常运行。开启伪静态后，URL 将从 /index.php?page=home 变为 /home，更美观。

如需开启：后台 → 系统设置 → 网站设置 → 伪静态配置。

6.5 维护模式

后台可开启全站维护模式，开启后前台显示维护页面，管理员仍可正常访问后台。

七、管理后台使用指南

7.1 访问后台

http://你的域名/admin/

使用安装时设置的管理员邮箱和密码登录。

7.2 管理功能速览

仪表盘（首页）查看核心运行数据：总用户数、总信件数、已发送/待发送数量、今日新增、发送成功率。

用户管理

• 搜索：按用户名、邮箱、ID 搜索
• 筛选：按状态（正常/禁用/封禁）、角色（用户/审核员/管理员）
• 操作：编辑用户信息、修改角色、启用/禁用/封禁、重置密码
• 查看：用户详细信息、发送记录

信件管理

• 查看全部信件的标题、作者、收件人、发送时间、状态
• 审核信件：通过 / 拒绝
• 批量操作：批量通过、批量拒绝、批量删除

评论审核

• 公开信评论列表，支持按状态筛选（待审/已通过/已拒绝）
• 批量审核操作
• 评论内容自动敏感词检测

开发者公告

• 接收查看授权服务器发来的公告通知
• 侧边栏红点提醒未读公告

订阅激活

• 输入订阅码激活年付或终身订阅
• 在后台 → 订阅管理 页面操作

系统设置

• 站点信息、邮件配置（含 SMTP 测试发送）
• 维护模式（手动/定时）
• 伪静态开关（付费功能）
• 内容审核开关

域名绑定

• 查看当前绑定域名
• 更换绑定域名

更新管理

• 检查是否有新版本
• 一键执行更新

八、定时任务详解

8.1 工作流程

cron/run.php 每分钟执行一次，自动完成：

• 发信：查询到期信件，逐封通过 SMTP 发送，失败自动重试（最多 3 次）
• 系统自检：定时校验站点运行状态

8.2 日志查看

# 查看定时任务日志
tail -100 /www/wwwroot/你的域名/logs/cron.log

# 实时监控
tail -f /www/wwwroot/你的域名/logs/cron.log

日志最长保留 5MB，超出自动裁剪到最近 3000 行。

8.3 手动执行测试

/www/server/php/81/bin/php /www/wwwroot/你的域名/cron/run.php

手动执行会直接输出所有日志到终端，便于排查问题。

九、常见问题排查

9.1 安装阶段问题

Q1：访问 install.php 显示 404 或空白页

最常见的 3 个原因（按概率排序）：

1. PHP 版本不是 8.1 → 宝塔 → 网站 → 你的域名 → PHP 版本 → 选 PHP-81 → 保存
2. 域名解析未生效 → 用 ping 你的域名 确认 IP 是否正确
3. 文件未上传到正确目录 → 确认 install.php 在 /www/wwwroot/你的域名/ 下

Q2：安装界面"环境检测"有红色 ❌

Q3：数据库连接失败

按以下顺序排查：

1. 数据库名、用户名、密码是否填错（注意不要有多余空格）
2. 数据库主机是否填的 127.0.0.1（不要填 localhost）
3. 数据库是否被删除 → 宝塔 → 数据库 → 查看是否存在

Q4：安装时一直转圈

原因：数据库信息有误或数据库用户权限不足。

解决方法：

1. 宝塔 → 数据库 → 找到对应数据库 → 点击 权限 → 确认为 ALL PRIVILEGES
2. 如果不是，改为 ALL PRIVILEGES 或删库重建

Q5：安装完成后访问首页仍跳转到 install.php

原因：安装程序未成功生成安装锁文件。

解决：

1. 访问 http://你的域名/install.php?reinstall=1 重新安装
2. 或手动创建锁文件：宝塔 → 文件 → 站点根目录 → 新建文件 installed.lock，内容任意

9.2 运行阶段问题

Q6：部分页面显示 404（如 /home、/compose）

原因：伪静态规则未配置或配置错误。

解决：

1. 宝塔 → 网站 → 你的域名 → 设置 → 伪静态
2. 确认内容为 Nginx rewrite 规则（见下方伪静态配置示例）
3. 不是下拉选择，是直接粘贴代码
4. 保存后重启 Nginx

location / {
    try_files $uri $uri/ @rewrites;
}
location @rewrites {
    rewrite ^/home$              /index.php?page=home last;
    rewrite ^/compose$           /index.php?page=compose last;
    rewrite ^/login$             /index.php?page=login last;
    rewrite ^/register$          /index.php?page=register last;
    rewrite ^/public$            /index.php?page=public last;
    rewrite ^/letter/([0-9]+)$   /index.php?page=letter_detail&id=$1 last;
    rewrite ^/(.*)$              /index.php?page=$1 last;
}

如果你使用的是 Apache，编辑 .htaccess 文件同样可以实现伪静态。

Q7：用户注册后收不到验证邮件

按顺序排查：

1. SMTP 配置是否已填写（后台 → 系统设置 → 邮件配置）
2. SMTP 授权码是否正确（QQ 邮箱是授权码不是密码）
3. 使用"测试发送"按钮验证配置
4. 检查邮箱垃圾箱

Q8：信件到达时间后没有发送

按顺序排查：

1. 定时任务是否配置（宝塔 → 计划任务 → 查看列表）
2. 定时任务是否执行（查看 logs/cron.log 是否有最近记录）
3. SMTP 配置是否正常（后台测试发送）
4. 手动执行一次测试：

/www/server/php/81/bin/php /www/wwwroot/你的域名/cron/run.php

5. 查看输出中的具体错误信息

Q9：页面显示 500 错误

解决步骤：

1. 查看错误日志：宝塔 → 网站 → 你的域名 → 错误日志
2. 或终端执行：

tail -50 /www/wwwroot/你的域名/logs/error.log
tail -50 /www/wwwlogs/你的域名.error.log

Q10：图片上传失败

可能原因：

1. uploads/ 目录权限不足 → 设为 777
2. PHP 上传限制太小 → PHP-8.1 → 配置修改 → 调大 upload_max_filesize 和 post_max_size
3. 磁盘空间不足 → 宝塔首页查看

Q11：页面样式错乱

按 Ctrl + F5 强制刷新浏览器缓存。如仍异常，检查浏览器控制台（F12）是否有 CSS 加载失败的提示。

Q12：SSL 证书到期

1. 宝塔 → 网站 → 你的域名 → 设置 → SSL
2. 如果使用了 Let's Encrypt，点击"续签"
3. 如使用付费证书，重新上传新证书

9.3 后台问题

Q13：后台无法登录

• 确认使用管理员邮箱登录（不是普通用户邮箱）
• 如忘记密码，通过数据库直接重置：宝塔 → 数据库 → 管理（phpMyAdmin）→ users 表 → 编辑管理员行的 password 字段

Q14：更新失败

• 检查 runtime/ 目录是否可写
• 查看后台错误日志了解具体错误
• 确认 .env 中的 SUBSCRIPTION_API_KEY 配置正确

宝塔面板常用操作速查

获取帮助

• 技术论坛： https://bbs.diuz.cn
• 演示站点： https://demo.timecaps.cn
• 开发者： 飞翔的丢
• 微信： HeyCziyi

时光邮局 v1.0.0 — 给未来的自己或他人写一封信，让时间为你送达。