Skip to Content
Qokit 用户手册

发布、预览或导出站点

生成团队预览,正式发布网站,连接域名,或下载独立部署包。

发布、预览或导出站点

根据网站的维护方式选择托管发布或导出。生成预览和正式发布都会绑定一个确定版本;之后的创作室修改不会自动进入线上网站。

生成团队预览

  1. 保存创作室修改,并确认发布检查已经完成。
  2. 在发布中选择生成预览。
  3. 等待状态显示预览已生成,再选择打开。
  4. 把预览链接发给需要确认的团队成员。
  5. 收集反馈后返回创作室修改、保存并重新生成预览。

每次预览都应检查首页、主要转化页面、手机视图、所有启用语言和表单。预览地址不应当作为正式域名长期对外宣传。

正式发布

  1. 确认当前创作室没有未保存修改。
  2. 确认发布检查中没有问题级项目。
  3. 选择发布。
  4. 等待状态显示站点已发布。
  5. 打开发布记录中的地址,从外部网络访问关键页面。
  6. 提交一次真实测试表单,并确认线索进入网站管理。

发布完成后记录负责人、时间和版本。继续编辑创作室不会改变当前线上版本,直到下一次发布。

查看发布历史和回滚

在发布 > 历史版本中查看当前生效版本和以前的发布记录。

需要恢复线上内容时:

  1. 先比较目标发布版本与当前版本。
  2. 选择回滚并确认。
  3. 等待系统切换生效版本。
  4. 重新打开公开地址检查。

回滚只改变线上生效版本,不会覆盖创作室草稿。需要继续编辑历史内容时,使用相应的“从此发布版本创建草稿”入口,不要假设画布已经同步回滚。

连接或注册域名

  1. 进入网站管理 > 设置 > 域名。
  2. 选择连接已有域名,按页面显示的 DNS 记录到域名服务商完成配置;或者在当前环境支持时搜索并注册新域名。
  3. 返回 Qokit 查看 DNS 和 SSL 状态。
  4. 等待域名状态就绪后,分别访问根域名和 www 地址。
  5. 检查 HTTPS、跳转、语言路径、表单和分享链接。

DNS 更新可能需要时间。状态尚未就绪时不要反复删除并重建连接;先核对记录名称和值是否完全一致。

导出网站

需要由自己的技术团队托管时,在发布区域选择导出。下载前确认当前套餐和角色具有导出权限。

选择导出类型

  • site-only:只导出带正文的静态 HTML 页面、样式、脚本和媒体资源。解压后打开根目录 index.html;其他页面在语言子目录中。包内没有安装向导、Node/Docker 服务、CMS 或站点 API。表单提交需要另外部署服务。
  • cms-managed:包含公开网站以及独立的网站后台,可以管理集合、内容、媒体、表单线索和营销草稿。
  • cms-only:独立 CMS 后台与内容 API,不包含公开网站渲染器,用于前端单独开发和部署。

网站运营人员需要在独立部署后继续发布新闻、上传媒体或管理营销内容时,应选择 cms-managed。

本地启动独立部署包

下面的步骤只适用于 cms-managed 和 cms-only 独立部署包;site-only 静态导出无需安装。部署包需要 Node.js 20.12 或更高版本。下载并解压后,在部署包目录执行:

cp .env.example .env

cms-managed 和 cms-only 部署必须先编辑 .env,至少替换以下配置:

PORT=3000
CMS_ADMIN_EMAIL=owner@example.com
CMS_ADMIN_PASSWORD=replace-with-at-least-12-characters
CMS_SESSION_SECRET=replace-with-at-least-32-random-characters
SITE_PUBLIC_URL=https://www.example.com

不要把示例密码或 Session 密钥用于正式环境。SITE_PUBLIC_URL 应填写访问者最终使用的 HTTPS 域名。

完成配置后执行:

npm run check
npm start

含公开网站的部署启动后可以访问:

  • 公开网站:http://localhost:3000/
  • 网站后台:http://localhost:3000/admin
  • 健康检查:http://localhost:3000/health

网站后台使用 .env 中的 CMS_ADMIN_EMAIL 和 CMS_ADMIN_PASSWORD 登录,不使用 Qokit 平台账号。

使用 Docker 部署

配置 .env 后执行:

docker compose up -d --build

容器默认暴露 3000 端口。正式环境应使用 Nginx、Caddy 或云负载均衡器把 HTTPS 域名反向代理到该端口。完成域名配置后,通过以下地址访问:

  • 公开网站:https://你的域名/
  • 网站后台:https://你的域名/admin
  • 健康检查:https://你的域名/health

独立部署主动连接 Qokit 获取签名更新并回传获准的运行状态或数据,因此通常不需要让 Qokit 直接访问部署服务器或数据库。保留部署包中的 data/update-config.json,并把它当作密钥文件保护。

数据持久化与备份

独立网站在导出后产生的数据不会自动写回原始内容快照:

  • data/runtime.json:集合、内容、表单线索和营销草稿等可变数据。
  • public/uploads:网站后台上传的媒体文件。
  • data/sync-outbox.jsonl:等待平台确认的数据同步事件。
  • data/update-backups:应用网站更新前生成的备份。

部署时必须持久化并定期备份 data 和 public/uploads。重新部署容器时不要用空目录覆盖这些路径。

平台连接与更新

cms-managed 和 cms-only 部署连接 Qokit 后,会使用安装实例身份向平台发送心跳。平台可以据此显示部署地址、最后在线时间、更新状态和同步状态。运行状态默认回传;内容、媒体元数据、营销内容和线索是否同步由安装实例的同步策略决定。

在网站后台的“更新”工作区可以检查和应用 Qokit 推送的签名版本;在“同步”工作区可以查看待同步事件并手动触发同步。运行时代码更新后如果页面提示需要重启,应重启站点进程或容器。

导出独立 CMS 包

site-only 是纯静态 HTML 网站;cms-managed 是网站与 CMS 的独立部署包;cms-only 包含 CMS 和内容 API,适用于前端单独部署的项目。

  1. 具有发布权限且套餐支持独立部署导出的成员,可以在项目卡片的更多菜单选择导出独立 CMS 包。创作室的工具 → 导出菜单也提供该入口。
  2. 下载并解压 ZIP,使用 Node.js 20.12 或更新版本。复制环境配置示例,再编辑 .env,替换管理员账号、密码和 Session 密钥:
cp .env.example .env

填写 CMS 服务的公开域名和外部网站域名。允许来源必须是逗号分隔的完整 HTTP(S) origin,不支持通配符。

CMS_ADMIN_EMAIL=owner@example.com
CMS_ADMIN_PASSWORD=replace-with-at-least-12-characters
CMS_SESSION_SECRET=replace-with-at-least-32-random-characters
CMS_PUBLIC_URL=https://cms.example.com
SITE_PUBLIC_URL=https://www.example.com
CMS_ALLOWED_ORIGINS=https://www.example.com,http://localhost:4321
  1. 配置完成后启动;运行时会自动读取 .env:
npm run check
npm start
  1. 打开 /admin,使用部署配置中的账号登录。根路径会跳转到 CMS,此包不提供网站页面。检查 /health,并通过 /api/content/collections/news/entries?locale=en 读取已发布内容。外部表单可提交到 /api/forms/contact/submissions。草稿不会公开,管理员登录仍限定在 CMS 自身域名。

持久化并备份 data 和 public/uploads,保护 data/update-config.json。更新会保留当前部署类型和本地数据。如果无法导出,检查角色和套餐权限;如果外部前端返回 403,核对允许来源配置并重启服务。

连接独立 CMS 到 Qokit

站点所有者可从独立 CMS 发起配对,并用自己的 Qokit 账号授权。目标项目所在工作空间须支持独立部署导出,账号须具有该项目的发布权限。

  1. 在独立网站后台打开系统设置 → 部署授权,选择 连接 Qokit。选择生成配对码,复制配对码,再选择 打开 Qokit。
  2. 选择目标项目并输入配对码。已有项目未显示时,切到项目所在的工作空间,检查项目是否已归档,以及当前账号是否有发布权限。网站只在独立 CMS 中时,先到目标工作空间新建项目,再返回配对窗口选择该项目。
  3. 选择 核对连接,核对项目、CMS 名称和地址后选择 确认绑定。返回独立网站后台,等待显示此 CMS 已连接 Qokit。

也可直接在 Qokit 打开目标网站,进入 系统设置 → 托管与交付 → 独立部署,选择 连接独立 CMS 并输入配对码。此入口使用当前项目。配对只登记安装实例并签发部署授权。配对码过期后,返回 CMS 选择 生成新配对码。

完成检查

  • 公开地址使用 HTTPS 并可以从外部网络访问。
  • 默认语言和其他启用语言的路径正确。
  • 导航、按钮、表单、分享图片和站点图标正常。
  • 线上版本和创作室草稿的状态已向团队说明。
  • 需要时已经验证回滚入口或独立部署备份。
这篇指南有帮助吗?

最后更新于

本页目录