快速上手：从安装到上线第一个网站

这篇文档写给第一次接触 KingCMS X1 的企业网站负责人。不需要先读开发文档，按顺序做完下面 8 步，就能把第一个网站发布到线上。文中命令以 Debian 13、nginx、PHP 8.4 为例，路径统一使用 /var/www/kingcms。

开始之前

适合谁：负责企业官网建设、需要自己动手部署一次再交给同事维护的人。

需要准备：

一台能 SSH 登录的服务器，已装好 nginx 或 Apache，PHP 8.2 或更高版本（X1.0.0-beta.1 要求 min_php 8.2）。
PHP 扩展：pdo_sqlite、sqlite3、sodium、mbstring、intl、curl、gd、xml、ctype、json、openssl、zip。
一个已解析到服务器的域名，以及可写的 data/ 目录。
站点根目录必须指向发布包里的 public/，app/ 和 data/ 要放在站点根之外，不能被浏览器直接访问。

1. 下载与校验

当前版本 X1.0.0-beta.1，2026-10-24 发布。发布包下载页：https://download.kingcms.com/。下载后先校验，不一致就不要解压部署。

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

校验值应为：

b433a7cc1081ab5cf4e3fbad3ff4709135307c972390d44f658934e242363ecc

2. 上传解压，站点根指向 public/

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

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

站点根目录指向 /var/www/kingcms/public，不要指向 /var/www/kingcms 或 app/。建议开启 OPcache，减少每次请求重新编译 PHP 文件的开销。

3. 目录权限与 nginx

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 {} \;

public/img/ 存放按尺寸生成的图片，同样须对 www-data 可写：

sudo mkdir -p /var/www/kingcms/public/img
sudo chown www-data:www-data /var/www/kingcms/public/img

首次访问时程序会自动创建 data/app.key，并把它设为 0600。app.key 用于加密设置里的密钥字段，不要删除、不要替换；丢失后已经加密的值无法解密。

nginx 精简要点：

root 指向 /var/www/kingcms/public，index 为 index.php。
location / 使用 try_files $uri $uri/ /index.php?$query_string;，否则内页会 404。
location /media/ 用 alias 指向 /var/www/kingcms/data/uploads/，并在该目录关闭 PHP 执行。
禁止访问点文件，保留 ACME 验证目录。
client_max_body_size 与 PHP 的 upload_max_filesize、post_max_size 保持一致，例如都设为 20m。
limit_req_zone 只能写在 http 上下文，放在单独的 conf 文件里。

完整配置、Apache 伪静态与 PHP 上传限制说明见 /docs/install。改完配置执行 nginx -t 检查，再 reload。

4. 首次访问自动建库，创建管理员

浏览器打开站点地址即可。data/kingcms.sqlite 不存在时，程序会自动创建 SQLite 数据库、执行迁移、写入默认设置并生成 data/app.key。没有分步安装向导，也不需要手工导入 SQL。

管理员还没有创建时，访问站点的任何页面都会跳转到 /admin/setup。在一次性设置页填写：

用户名：不能为空，最多 64 个字符。
密码：至少 8 个字符，并再次确认。
「写入示例内容（可删除）」复选框：可勾选，先看看前台效果。
「商品价格是否含税」：不含税 / 含税，必选。
站点时区：自动按浏览器填写。
同意授权协议（X1 v2.3）。

创建成功后当前浏览器自动登录并跳转到后台首页 /admin，/admin/setup 永久返回 404，不能再用于创建第二个管理员。之后登录地址为 /admin/login。

5. 填写站点基本信息

进入后台「系统设置 → 设置」，把下面这些字段填完整：

分组	字段	说明
基本信息	站点名称	企业对外展示的名称
基本信息	网站网址	正式访问地址
基本信息	前台 Logo	前台页头使用的图片
基本信息	站点时区	按实际时区填写
基本信息	网址形式	按需要选择
联系与组织	组织名称	用于首页 Organization 结构化数据
联系与组织	联系电话	对外联系方式
联系与组织	联系地址	对外联系地址
备案	ICP 备案号	按实际备案信息填写
备案	公安备案号	按实际备案信息填写
备案	公安备案链接	按实际备案信息填写

已启用语言、默认语言在「设置 → 内容与媒体」。默认标题、默认关键词、默认描述、分享标题/描述/图片在「营销与 SEO → SEO → 设置」。前台默认主题会输出 meta description、canonical、hreflang 与 og:title/description/url/image，并输出 Organization、WebPage、Article、Product/Offer、BreadcrumbList、FAQPage、CollectionPage、ItemList 等 JSON-LD 类型。

6. 新建第一个单页栏目并发布

在「系统设置 → 栏目管理」点「添加」，表单字段为上级栏目、名称、类型（文章列表/单页/商品列表）、栏目简介、缩略图。类型选择「单页」，适合关于我们、联系我们这类内容。路径由名称自动生成（中文转拼音），没有路径名和排序字段，排序用拖动。

保存后点「编辑」，才有正文、SEO 标题/关键词/描述、常见问题（FAQ）、对访客可见、进导航。正文编辑器支持标题、列表、链接、图片、表格等常用格式。列表里有「查看」。

单页和商品都有 FAQ 区块，填写后会输出 FAQPage JSON-LD；文章和栏目列表没有。多语言站点在编辑页用语言标签填写译文，未填译文前台回落中文。改名时勾选「重新生成路径」，旧路径自动 301；只有勾选重新生成路径才改地址。

保存并发布后，回到前台确认页面能正常打开。如果首页正常而内页 404，先检查第 3 步的重写配置。

7. 配置 cron 与 HTTPS

cron 负责执行已启用模块登记的每分钟钩子，并处理到期的后台任务。在 /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 可写。

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

8. 上线前检查清单

站点根指向 public/，app/ 与 data/ 不在站点根内。
data/ 与 public/img/ 属主为 www-data，app.key 权限为 0600。
首页与内页都能打开，没有 404。
上传一张图片，确认 /media/ 下能正常显示且不执行 PHP。
站点名称、网址、Logo、联系电话、地址、ICP 备案号、默认标题与描述已填写。
第一个单页栏目已发布，SEO 标题与描述已填。
cron 已配置，data/ 可写。
HTTPS 已启用。
访问 /sitemap.xml、/robots.txt、/llms.txt 确认输出正常。
数据库与 app.key 已一起备份，备份文件放在站点目录之外。

需要搜索引擎收录时，在「系统设置 → 模块与主题」中确认「搜索引擎收录」模块已启用（beta.1 全新安装后实测已是启用状态）。在「营销与 SEO → SEO → 设置」页点「显示高级设置」，可配置百度/搜狗站点验证、百度普通收录推送（开关）、百度站点地址、百度推送 token、IndexNow 推送、头条/360 JS 自动提交。推送日志在该页「推送日志」标签。腾讯元宝等 AI 助手没有公开提交入口，KingCMS 也没有针对豆包、DeepSeek、元宝的专用设置。

本地先试用

只想在本机看看界面，在解压后的目录执行一行命令：

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 创建管理员。内置服务器只适合本地试用，不要用于正式站点。