# JLKE Kaelo 部署文档
## 文档基础信息
项目名称：JLKE Kaelo（JLKE GROUP主机/服务管理系统）
运行架构：PHP + SQLite（文件型数据库）
Web服务支持：Nginx / Apache
适配系统：Windows、Linux（Debian/Kali等）、低功耗机顶盒Linux容器
适用PHP版本：7.4 ~ 8.x
开发归属：JLKE GROUP

---

## 一、环境前置依赖准备
### 1. PHP必须开启扩展
部署前确认PHP已启用以下核心扩展，缺失会导致程序初始化失败：
1. `pdo_sqlite`：SQLite文件数据库核心驱动（必装）
2. `mbstring`：中文字符编码处理
3. `gd`：图片上传、头像渲染
4. `openssl`：密码bcrypt加密、临时密钥生成
5. `fileinfo`：上传文件类型校验

### 2. Web服务基础要求
1. Nginx/Apache支持PHP-FPM解析；
2. 站点目录、上传目录需授予**读写权限**；
3. 生产环境关闭PHP页面错误打印，屏蔽敏感报错信息。

### 3. 磁盘与权限说明
1. 源码根目录：需可写，首次访问自动生成SQLite数据库文件；
2. `uploads`上传目录：最高读写权限，用于存储用户头像、业务截图；
3. 数据库文件`.sqlite`禁止外部直接下载访问。

---

## 二、一键部署步骤（通用流程）
### 步骤1：上传源码包
1. 将完整源码压缩包上传至Web站点根目录；
2. 解压全部文件，保证目录结构完整（`admin`/`user`/`supplier`/`staff`/`assets`/`uploads`等文件夹不可缺失）；
3. 服务器端执行权限赋权（Linux示例）
```bash
# 站点目录整体权限
chmod -R 755 /你的站点根目录
# 上传目录开放写入权限
chmod -R 777 /你的站点根目录/uploads
```

### 步骤2：访问站点自动初始化
1. 浏览器打开站点域名/IP，程序自动执行初始化流程：
   - 自动创建SQLite数据库文件；
   - 自动生成全部数据表、默认爬虫白名单；
   - 生成初始超级管理员账号；
2. 初始化完成后跳转登录页面，使用默认管理员账号登录后台。

> 注意：无需手动创建数据库、导入SQL文件，全程零数据库配置。

### 步骤3：后台初始安全配置（必做）
1. 登录超级管理员后台，进入安全中心；
2. 修改默认超级管理员账号密码；
3. 配置爬虫访问白名单、IP黑白名单；
4. 设置登录访问限流阈值，开启验证码防护。

---

## 三、Nginx 生产环境标准配置
### 完整站点conf配置示例
```nginx
server {
    listen 80;
    server_name 你的域名;
    root /站点完整根目录;
    index index.php index.html;

    # 禁止直接访问sqlite数据库文件
    location ~* \.sqlite$ {
        deny all;
        return 403;
    }

    # 禁止uploads目录执行PHP脚本，防上传木马
    location ~* ^/uploads/.*\.php$ {
        deny all;
        return 403;
    }

    # PHP解析规则
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # 静态资源缓存优化
    location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }
}
```

### Apache简易配置说明
1. 开启`mod_rewrite`伪静态模块；
2. 在根目录放置`.htaccess`，拦截数据库、上传目录PHP执行；
3. 目录权限规则与Nginx保持一致。

---

## 四、低功耗特殊设备部署（机顶盒Linux容器）
适配场景：安卓4.4机顶盒GNURoot Debian容器内网部署
1. 容器内安装PHP7.4+、Nginx，补齐全部依赖扩展；
2. 源码挂载至U盘持久化存储，避免盒子内置eMMC容量不足；
3. 配置HDMI虚拟欺骗头，防止机顶盒休眠断网、杀掉Web后台进程；
4. 仅对内网开放访问，**禁止直接对公网暴露端口**（老旧安卓底层存在漏洞）；
5. 定时rsync同步数据库备份至NAS，规避SQLite并发数据错乱问题。

---

## 五、生产环境运维规范（关键）
### 1. 数据库风险规避（SQLite并发缺陷）
1. 定时自动备份`.sqlite`数据库文件，建议每4小时备份一次；
2. 限制单IP高频请求频率，减少并发读写造成白名单重复、数据损坏；
3. 数据库错乱兜底方案：停机后替换备份库，或手动编辑sqlite文件清理异常数据。

### 2. 超级管理员权限管控（权限互锁漏洞临时方案）
1. 全程仅保留**1名默认超级管理员**，不新增次级超级账号；
2. 员工、合作方仅分配客服/供应商权限，绝不授予最高管理员身份；
3. 若误授予超级权限，后台无法回收，处理流程：
   - 停止Nginx站点服务；
   - 使用SQLite工具打开数据库，修改对应用户角色字段；
   - 重启站点，权限即可回收。

### 3. 日志与审计运维
1. 系统自动留存60天操作日志，定期导出日志归档；
2. 注意：超级密码、临时密钥生成操作存在日志漏采集问题，重要密钥线下额外留存记录；
3. 日志记录IP为服务器获取的外网IP，内网集群环境需自行适配内网IP采集分支。

### 4. 后台BUG使用提示
1. 普通用户修改密码功能正常；超级管理员修改自身密码存在逻辑BUG，页面提示成功但数据不更新，管理员建议使用临时超级密码登录；
2. 前台用户浏览、下单、个人资料修改全部稳定，所有异常仅影响后台管理操作，不对外业务产生影响。

---

## 六、常见部署报错排查
1. **页面空白/500错误**
   排查：PHP扩展缺失、站点目录无读写权限、PHP版本过低。
2. **初始化失败，无数据库文件生成**
   排查：根目录未授予写入权限、pdo_sqlite扩展未开启。
3. **上传头像/截图失败**
   排查：uploads目录权限不足、gd扩展未启用。
4. **爬虫白名单无限重复、无法删除**
   根因：SQLite文件数据库并发读写冲突，解决方案：重启站点+回滚数据库备份。
5. **超级管理员改密码无效**
   已知分支BUG，短期无修复方案，改用临时超级密钥登录。

---

## 七、部署免责&开源使用提示
1. 本项目仍处于迭代阶段，存在数据库并发异常、权限互锁、日志缺失等已知缺陷；
2. 不建议无任何防护直接裸奔公网商用，线上部署必须搭配IP白名单、高频限流、定期备份；
3. 后台管理类BUG短期内不会优先修复，风险规避完全依赖使用者运维规范；
4. 项目仅推荐内网测试、学习二次开发、小型内网业务使用。