部署指南（Apache / Nginx）

最后更新 2026-07-29 ·生产环境的目录权限、伪静态配置与上线检查。

Web 根目录

Web 根目录必须指向 public/，不能指向项目根目录。

config/config.php 包含数据库凭据，storage/ 保存日志、缓存、备份和 SQLite 数据文件。这些目录位于 public/ 之外。站点根目录指向项目根时，配置和运行数据可能被公开访问。

目录权限

# 需要可写
chmod -R 775 storage public/uploads
chown -R www-data:www-data storage public/uploads config

# 其余核心目录尽量保持只读
chmod 640 config/config.php

config/config.php 只需要部署用户和 PHP 运行用户能读。

Apache

发行包自带 public/.htaccess，需要 mod_rewrite 且虚拟主机允许覆盖：

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /www/wwwroot/example.com/public

    <Directory /www/wwwroot/example.com/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

如果没有启用 AllowOverride All，.htaccess 不会生效，动态路由将返回 404。

Nginx

Nginx 不读取 .htaccess，需要在 server 块中配置改写规则。try_files 会把未命中静态文件的请求交给入口文件。

server {
    listen 80;
    server_name example.com;
    root /www/wwwroot/example.com/public;
    index index.php;

    client_max_body_size 20m;

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

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # 上传目录只当静态文件出，绝不执行 PHP
    location ^~ /uploads/ {
        location ~ \.php$ { deny all; }
        expires 30d;
    }

    location ~ /\. { deny all; }
}

HTTPS 与站点网址

启用 HTTPS 后，在后台「设置」中把站点网址填写为带 https:// 的完整地址。canonical、hreflang、sitemap、RSS 和分享图会使用该值生成绝对地址；配置错误会产生错误域名的链接。

伪静态后缀

后台「设置」中的 URL 后缀决定详情页和单页地址：留空时为 /news/hello，填写 .html 时为 /news/hello.html。站点上线后变更该设置会改变现有内容地址。变更前应在后台「重定向」中配置旧地址到新地址的 301 跳转。

上线检查

php bin/cms.php migrate        # 执行尚未运行的编号迁移
php bin/cms.php health         # 检查环境、配置和数据库状态
php bin/cms.php backup         # 创建数据库备份

然后逐项确认：

  • 删除了 public/install.php
  • 前台首页、列表、详情、单页、搜索、联系表单、404 都正常
  • 后台能登录，内容能保存，媒体能上传
  • /sitemap.xml、/robots.txt、/feed.xml、/llms.txt 都能打开
  • storage/logs/ 里没有解释不了的报错
  • 配置好了日志轮转、备份保留和磁盘告警

性能相关的开关

  • 整页缓存默认关闭（TTL 为 0）。内容更新不频繁的站点可以在设置中配置缓存秒数。缓存只用于匿名访客的前台 GET 请求，后台写操作会清空缓存。
  • 全文搜索默认使用 LIKE 模糊匹配。MySQL 环境可以执行 php bin/search-index.php 建立全文索引后再开启全文搜索；未开启时继续使用 LIKE 查询。