安装部署

一、环境要求

系统基于 PHP 8 与 SQLite 构建，不需要单独安装 MySQL 等数据库服务，一台普通云主机即可运行。

必需的 PHP 扩展：

二、上传代码与目录结构

将系统代码上传至服务器后，目录结构如下（重点是 public/ 与 database/ 同级）：

三、配置环境变量

复制 .env.example 为 .env，按实际情况修改：

APP_NAME=教籍册管理系统
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain/
APP_KEY=请填写32位随机字符串

DB_MODE=single
DB_PATH=database/jiaojice.db

SESSION_SECURE=true
SESSION_LIFETIME=7200

• APP_ENV：生产环境填 production，会关闭错误显示。
• APP_KEY：32 位随机串，用于加密签名，请勿使用示例值。
• DB_MODE：single 为单教区模式，multi 为多教区 SaaS 模式。
• SESSION_SECURE：站点启用 HTTPS 后必须设为 true。

四、配置伪静态

系统依赖伪静态实现简洁 URL。三个平台的规则如下。

Nginx（宝塔面板）

在站点设置的「伪静态」中填入：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Apache

public/.htaccess 已内置，只需确保虚拟主机配置了 AllowOverride All。

IIS

public/web.config 已内置，需服务器安装 URL Rewrite 模块。

五、安装依赖（可选）

系统核心功能无需 Composer 依赖即可运行。只有 AI 报告 PDF 导出需要 mPDF：

composer install --no-dev --optimize-autoloader

未安装时，PDF 导出会自动回退为浏览器打印，不影响其他功能。

六、首次登录与初始设置

1. 访问登录页

   浏览器打开 https://your-domain/login，使用开通时提供的初始账号登录。

2. 立即修改密码

   首次登录或重置密码后，系统会强制要求修改密码才能继续使用。

3. 设置系统参数

   进入「系统设置」，填写系统标题，并按教区习惯自定义层级名称（如「堂区」改为「分堂区」）。

4. 建立组织架构

   依次创建教区 → 堂区 → 堂口。单教区使用可只建一个教区。

5. 配置标签与参数

   在标签管理中预设称谓、团体、片区等常用标签，录入成员时即可直接选择。

七、备份策略

SQLite 是单文件数据库，备份极为简单——复制这个文件即可。系统支持热备份（.backup 命令不锁库），无需停机。

# 每日备份示例（加入 crontab）
sqlite3 database/jiaojice.db ".backup '/backup/jiaojice_$(date +%F).db'"

# 仅保留 30 天
find /backup -name "jiaojice_*.db" -mtime +30 -delete

• 建议每日备份一次，保留 30 天。
• 备份文件应存放到服务器以外的位置（如另一台机器或网盘）。
• 操作日志建议每月导出归档一次。

八、故障排查