环境要求与 Web 安装向导

一、环境要求

服务端只需要 PHP 与 MySQL，不需要 Node.js、Redis 或 Docker。

• PHP 8.1 及以上（安装向导会检测版本，低于 8.1 直接拦截）
• MySQL 8.0，字符集 utf8mb4，排序规则 utf8mb4_general_ci
• Web 服务器：Nginx 或 Apache 均可，需要支持伪静态

PHP 扩展必须开启以下几项，缺任意一个都会在环境检测这一步标红：

pdo_mysql  mbstring  openssl  curl  zip  fileinfo  gd

二、目录权限

以下目录必须对 PHP 进程可写，其余目录建议只读：

• /runtime 运行时缓存与日志
• /public/html 静态化产物输出目录
• /public/uploads 上传文件目录
• /app/common/library/install 安装器写入配置
• 根目录 .env 文件（首次安装需要创建，装完可改为只读）

三、安装步骤

1. 把整包上传到站点目录，Web 根指向 /public
2. 浏览器访问你的域名；若尚未安装，入口会自动 302 到 /install.php
3. 环境检测 → 填写数据库信息 → 设置超级管理员账号密码 → 提交
4. 安装完成会生成 public/install.lock，此后不再进入向导

安装向导地址也可以手动访问：https://你的域名/install.php。若已存在 install.lock，向导会拒绝再次执行，这是防止误重装的第一道保护。

四、伪静态配置

Nginx 的最小可用配置如下（try_files 让静态页优先，其余交给入口文件）：

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

location ~ ^/(admin|api)/ {
    try_files $uri /index.php$is_args$args;
}

Apache 用户使用整包内附的 .htaccess 即可，无需改动。

五、装完第一件事

登录后台（/index.html#/admin）后，先做两件事：

1. 在「系统设置」里确认站点域名与站点名称
2. 执行一次静态化：php think static:build all

这两步做完，前台就已经是一套可以对外访问的完整站点。

六、常见报错

• 提示目录不可写：注意是 PHP 进程用户（如 www-data）需要可写，不是你的登录用户
• 连接数据库失败：先确认 pdo_mysql 扩展已加载，再确认数据库账号允许从本机连接
• 页面 404 但文件存在：伪静态没生效，检查 try_files 是否指向 /index.php