本文说明 KingCMS X1.0.0-alpha 的安装、首次访问、在线更新、备份与定时任务。站点根目录必须指向发布包中的 public/，首次访问会自动创建数据库，没有分步安装向导。

1. 环境要求

  • PHP 8.2 或更高版本。本文示例使用 Debian 13 自带的 PHP 8.4。
  • PHP 扩展：pdo_sqlite、sqlite3、sodium、mbstring、intl、curl、gd、xml、ctype、json、openssl。图片处理依赖 gd，在线备份依赖 sqlite3；「连同上传文件」备份还需要 zip 扩展。
  • SQLite 3（手动备份时使用 sqlite3 命令行）。
  • Web 服务器使用 nginx（本文示例）或 Apache，PHP 通过 PHP-FPM 运行。
  • 可写的 data/ 目录。SQLite 数据库、app.key、缓存和上传文件都放在这里。

app/ 和 data/ 必须位于站点根之外，不能被浏览器直接访问。站点根只指向 public/。

2. 下载与校验

发布包下载页：https://download.kingcms.com/。当前版本 X1.0.0-alpha（2026-10-20 发布），文件约 16.4 MB，已签名。

wget https://update.kingcms.com/stable/kingcms-x1-X1.0.0-alpha.zip
sha256sum kingcms-x1-X1.0.0-alpha.zip

校验值应为：

278bdb5d4a1cb1ca480b7e0802cc8773d69664f58194eb72ee59546a29490767

不一致时不要解压部署，请重新下载。

3. 安装软件包

以 Debian 13 为例：

sudo apt update
sudo apt install -y \
  nginx \
  php8.4-fpm php8.4-cli php8.4-sqlite3 php8.4-mbstring \
  php8.4-intl php8.4-curl php8.4-gd php8.4-xml \
  sqlite3

sodium 由 PHP 8.4 的 common 包提供，不需要单独安装。

检查 PHP 扩展

for ext in pdo_sqlite sqlite3 sodium mbstring intl curl gd xml ctype json openssl; do
  php -r 'exit(extension_loaded($argv[1]) ? 0 : 1);' "$ext" \
    || echo "缺少扩展：$ext"
done

没有输出即表示扩展齐全。Web 端和命令行使用同一套 PHP 包；扩展是后装的时候，先重启 PHP-FPM：

sudo systemctl restart php8.4-fpm

4. 上传与解压

把发布包上传到服务器并解压。示例路径是 /var/www/kingcms：

sudo mkdir -p /var/www/kingcms
sudo unzip kingcms-x1-X1.0.0-alpha.zip -d /var/www/kingcms

压缩包内包含 app/、bin/、modules/、public/、resources/、themes/、vendor/。依赖已经随包提供，不需要执行 composer install。

站点根目录指向 /var/www/kingcms/public，不要指向 /var/www/kingcms 或 app/。

建议在 php.ini 或 PHP-FPM 池里开启 OPcache，减少每次请求重新编译 PHP 文件的开销：

opcache.enable=1
opcache.memory_consumption=128
opcache.validate_timestamps=1

部署新版本后，若 validate_timestamps=0，需要重载 PHP-FPM 才会生效。

5. 目录权限

data/ 需要由运行网站的用户（通常是 www-data）写入：

cd /var/www/kingcms
sudo mkdir -p data/uploads data/cache
sudo chown -R www-data:www-data data
sudo find data -type d -exec chmod 750 {} \;
sudo find data -type f -exec chmod 640 {} \;

首次访问时程序会自动创建 data/app.key，并把它设为 0600。确认权限：

sudo chmod 600 /var/www/kingcms/data/app.key
sudo ls -l /var/www/kingcms/data/app.key

app.key 用于加密设置里的密钥字段。不要删除、不要替换；丢失后，已经加密的值无法解密。

6. nginx 配置

先在 /etc/nginx/conf.d/kingcms-limit.conf 放置限流区。limit_req_zone 只能写在 http 上下文，所以放在单独的 conf 文件里：

limit_req_zone $binary_remote_addr zone=kingcms:10m rate=10r/s;

站点配置 /etc/nginx/sites-available/kingcms：

server {
    listen 80;
    server_name cms.example.com;

    root /var/www/kingcms/public;
    index index.php;

    # 默认 20MB，与 upload_max_filesize、post_max_size 保持一致；
    # 站点只收小图时可以降到 8m。
    client_max_body_size 20m;

    gzip on;
    gzip_comp_level 5;
    gzip_min_length 860;
    gzip_types text/css application/javascript application/json image/svg+xml;

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

    # 本地上传文件：指向站点根之外，关闭 PHP 执行。
    location /media/ {
        alias /var/www/kingcms/data/uploads/;
        add_header Cache-Control "public, max-age=2592000";

        location ~ \.php$ {
            return 404;
        }

        location ~ /\. {
            deny all;
        }
    }

    # 禁止访问点文件（保留 ACME 验证目录）。
    location ~ /\.(?!well-known) {
        deny all;
    }

    # 远程 MCP：GET 使用 SSE 长连接，关闭缓冲并放宽读取超时。
    # 未开启远程 MCP 时，这个 location 也会由程序返回 404。
    location = /mcp {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        fastcgi_buffering off;
        fastcgi_read_timeout 3600s;
        fastcgi_send_timeout 3600s;
        limit_req zone=kingcms burst=20 nodelay;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        limit_req zone=kingcms burst=20 nodelay;
    }
}

启用并检查：

sudo ln -s /etc/nginx/sites-available/kingcms /etc/nginx/sites-enabled/kingcms
sudo nginx -t
sudo systemctl reload nginx

正式启用前应配好 HTTPS。微信、支付宝回调和 Secure cookie 都依赖 HTTPS。

PHP 上传限制

在 /etc/php/8.4/fpm/conf.d/99-kingcms.ini 写入：

upload_max_filesize = 20M
post_max_size = 20M

这两个值要与 nginx 的 client_max_body_size 一致或更大。修改后重启 PHP-FPM：

sudo systemctl restart php8.4-fpm

7. Apache 伪静态

Apache 需要满足两个条件：

  1. 开启 mod_rewrite：a2enmod rewrite，然后重启 Apache。
  2. 站点目录允许 .htaccess 覆盖配置，即 AllowOverride All。
<VirtualHost *:80>
    ServerName cms.example.com
    DocumentRoot /var/www/kingcms/public

    <Directory /var/www/kingcms/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

站点根目录 public/ 中已带有 .htaccess，内容如下。它只把不存在的文件和目录转给 index.php，并保留查询串：

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [QSA,L]

前台地址（例如 /news/hello-world）只是访问路径，磁盘上并不存在对应目录。除真实存在的文件（如 /assets/...、图片）和目录外，其他请求都要交给 index.php 处理。没有重写规则时，服务器会直接返回 404，内页无法打开。

8. 首次访问自动建库

浏览器打开站点地址即可。data/kingcms.sqlite 不存在时，程序会自动：

  1. 创建 SQLite 数据库；
  2. 执行内核迁移，建表并写入默认设置；
  3. 执行已安装模块的迁移；
  4. 生成 data/app.key。

没有分步安装向导，也不需要手工导入 SQL。默认设置包括站点名称「KingCMS」、已启用语言 zh-CN,en、主题 default 等。

9. 创建管理员

管理员还没有创建时，访问站点的任何页面都会跳转到 /admin/setup（静态资源 /assets/ 和 /healthz 除外）。在一次性设置页填写：

  • 用户名：不能为空，最多 64 个字符；
  • 密码：至少 8 个字符；
  • 确认密码：必须与密码一致；
  • 可选：是否创建示例内容；
  • 同意授权协议。

创建成功后，管理员账号写入数据库，当前浏览器自动登录并跳转到后台首页 /admin；/admin/setup 永久返回 404，不能再用于创建第二个管理员。设置页对同一 IP 限制为 15 分钟内最多 5 次提交。

登录地址为 /admin/login。忘记管理员密码时，在包含 public/ 的目录执行：

cd /var/www/kingcms
sudo -u www-data php bin/kingcms admin:reset-password

按提示输入新密码，命令会退出该管理员的全部旧会话。

10. 在线更新

在线更新通道已开放。后台「系统设置」中的更新页面会读取 https://update.kingcms.com/stable/latest.json，与当前版本比较后提示可用的新版本，并显示发布说明与校验信息。

  • 更新前先备份数据库与 app.key（见下一节）。
  • 更新会替换程序文件，保留 data/ 目录（数据库、app.key、上传文件、缓存）。
  • 更新后如开启了 OPcache 且 validate_timestamps=0，需要重载 PHP-FPM。
  • 也可以手动下载新版本发布包，按第 2 节校验后覆盖程序文件，保留 data/。

11. 备份

SQLite 与 app.key 必须一起备份：换了密钥，数据库里加密的字段就无法解密。

sudo install -d -m 700 /var/backups/kingcms
sudo sqlite3 /var/www/kingcms/data/kingcms.sqlite \
  ".backup '/var/backups/kingcms/kingcms-$(date +%F).sqlite'"
sudo install -m 600 /var/www/kingcms/data/app.key \
  /var/backups/kingcms/app.key

用 sqlite3 .backup 而不是直接复制正在使用的 .sqlite 文件。备份放在站点目录之外。上传文件在 data/uploads/，需要时一并备份。后台「数据备份」页也可以一键备份、下载、删除和恢复，并配置每天或每周的定时备份。

注：网站运行中备份时，请使用后台「数据备份」功能或 sqlite3 .backup，不要直接复制正在使用的数据库文件；数据库需与 app.key 一起备份。

12. cron

php bin/kingcms cron:run 负责执行已启用模块登记的每分钟钩子，并处理到期的后台任务，例如释放超时订单的库存预占、ntfy 推送。统计模块启用时，它还会汇总访问数据并清理旧明细。

在 /etc/cron.d/kingcms 写入：

SHELL=/bin/sh
PATH=/usr/local/bin:/usr/bin:/bin
* * * * * www-data /usr/bin/php /var/www/kingcms/bin/kingcms cron:run >/dev/null 2>&1

cron:run 使用 data/cron.lock 保证同时只运行一个。确认 data/ 对 www-data 可写。

13. 本地快速试用

只想在本机看看界面时，可以用 PHP 内置服务器，在解压后的目录执行：

php -S 127.0.0.1:8080 -t public public/index.php

然后打开 http://127.0.0.1:8080。首次访问会自动创建 data/、data/kingcms.sqlite 与 data/app.key，随后进入 /admin/setup 创建管理员。内置服务器只适合本地试用，不要用于正式站点。

14. 常见问题

首页正常，内页显示 404。 说明重写没有生效。nginx 检查是否配置了 try_files ... /index.php?$query_string；Apache 检查是否已开启 mod_rewrite，以及站点目录是否设置了 AllowOverride All。

首页也是 404。 检查站点根是否指向 public/，以及 public/index.php 是否存在。

上传的图片打不开。 图片保存在 data/uploads/，不在站点根内。nginx 按第 6 节的 /media/ 别名配置；Apache 同样需要把 /media/ 别名到该目录，并禁止在该目录执行 PHP。

修改了栏目或文章地址，旧地址打不开。 程序会自动为旧地址保存 301 跳转，无需手动配置。

后台设置「单个文件上限（MB）」填了 20，上传仍失败。 检查 PHP 的 upload_max_filesize、post_max_size 与 nginx 的 client_max_body_size 是否都已调大。

15. 授权

前台 Powered by KingCMS 链接的保留与移除要求以现行授权协议为准。需要移除版权链接时，需取得相应授权，详见 价格与授权。