上传到站点根目录即可（入口 index.php 位于根目录，无需单独运行目录）。首次访问 install.php 进入安装向导，完成环境检查、填写数据库和管理员账号后自动建库建表。

运行环境：PHP 8.1+、MySQL 5.7.6+、Nginx 或 Apache。单一数据库即可，无需 Redis 等额外服务。

index.php      # 入口（站点根）
install.php    # 安装向导（安装后请删除）
config.php     # 安装生成
app/           # 应用代码
public/        # 静态资源（css/js/uploads/vendor）
themes/        # 主题
plugins/       # 插件
migrations/    # 数据库迁移

Nginx 只需一条伪静态：try_files / /index.php?;。静态资源走 /public/ 直链，Web 服务器任何配置下都能加载，无需额外静态规则。Apache 使用内置 .htaccess。

宝塔面板：新建站点 → 上传程序包解压到站点根目录 → 设置伪静态为上述规则 → 访问域名进入安装向导。数据库可在宝塔创建，或在安装向导中填写已有的库。

安装向导生成 config.php，包含数据库连接信息。站点设置在后台「站点设置」页完成：站点信息（名称、副标题、备案号）、SMTP 邮件（支持测试发送）、开放 API 开关、应用商店地址、Markdown 安全开关等。

定时发布双通道：宝塔计划任务调用 cron.php（推荐），前台请求低频兜底（无需配置即可生效，但精度较低）。

会话默认 7 天；忘记密码支持邮箱验证与 SMTP 双通道。

主程序内置官方应用商店（store.waikanl.cn），开箱即用，地址硬编码无需配置。后台「商店」页可直接浏览、安装、更新主题与插件；目录拉取失败时自动回退内置商店，商店永不自挂。

站点设置中也可配置社区或私有商店地址，应用源使用同一套 runtime-store/v1 JSON 协议。商店目录缓存 1 小时，安装/更新前校验包的 SHA-256 完整性。

付费应用：在站点设置填写授权码（官网购买后提供，仅保存在服务器），商店下载付费应用时自动携带授权码与站点地址。

{
  "apps": [
    {
      "type": "theme",
      "slug": "default-pro",
      "version": "1.0.0",
      "sha256": "...",
      "download_url": "https://...",
      "requiresPafish": "0.1.0"
    }
  ]
}

主题使用 theme.json 声明元信息与设置项，后台按字段生成设置页。前台样式 style.css 放在主题目录内，由系统内联注入（与 theme.css 变量一起），主题切换即换全套样式。

主题目录结构：

my-theme/
├─ theme.json     # 元信息与设置项声明
├─ theme.css      # 语义 CSS 变量（颜色/字体）
├─ style.css      # 前台布局样式
├─ header.php     # 头部模板
├─ footer.php     # 底部模板
├─ post.php       # 文章模板
├─ page.php       # 页面模板
└─ assets/        # 静态资源

theme.json 示例：

{
  "name": "My Theme",
  "version": "1.0.0",
  "author": "你的名字",
  "config": [
    { "key": "accent", "label": "主色调", "type": "color", "default": "#0d9488" }
  ]
}

语义 CSS 变量在 theme.css 中定义，模板通过 asset_url() 输出资源路径。第三方主题未提供 style.css 时回退默认主题布局，保证始终有样式。

插件通过 plugin.json 声明，返回一个数组注册事件钩子。插件 API v2 支持过滤器（()，可统一注销）、首次/定时/批量发布事件、文章保存扩展字段、SEO Meta、Markdown 预处理、上传预处理，以及评论/登录/注册前置策略。

插件目录结构：

my-plugin/
├─ plugin.json     # 元信息
├─ index.php       # 主文件，返回钩子数组
└─ assets/         # 静态资源（可选）

plugin.json 示例：

{
  "name": "My Plugin",
  "version": "1.0.0",
  "apiVersion": 2
}

主文件返回钩子数组，通过 ` 读写数据、记录日志、注册过滤器与 UI 插槽。卸载回调可在持久化数据清理前完成资源回收。详细 API 见主程序docs/plugins.md`。

系统内置开放 API v1，使用 X-API-Key 鉴权。在后台「站点设置 → 开放 API」开启并生成密钥后，可通过 API 发布文章、管理分类标签、查询内容等，便于外部工具（采集器、笔记同步、小程序）对接。

请求头携带 X-API-Key: 你的密钥，响应为 JSON。API 路径自动适配伪静态/非伪静态两种部署。

GET  /api/posts          # 文章列表
POST /api/posts          # 发布文章
GET  /api/posts/{id}     # 文章详情
GET  /api/categories     # 分类列表

后台「系统更新」页检查主程序新版本并一键升级。升级前自动整站备份（排除 runtime/backups/public/uploads 与 config.php），失败自动回滚。支持包内 upgrade.php 迁移脚本，配合 Migrator 服务执行增量数据库迁移。

数据库迁移：schema_migrations 表记录已应用版本，存量库自动识别基线，增量迁移幂等可重跑。新装与老装走同一条演进路径。

升级如有异常，可从备份恢复：后台「备份」页支持整站备份与数据库备份双模式。

样式加载不出来？ 静态资源走 /public/ 直链，Nginx 只需 try_files 伪静态即可，无需额外静态规则。若仍异常，确认 public/ 目录随程序包上传完整。

后台登录提示网络错误？ 前端 API 走 pafishApi() 统一入口，自动适配伪静态/非伪静态。确认站点伪静态规则已生效，且未在子目录部署时遗漏前缀。

定时发布不生效？ 推荐宝塔计划任务调用 cron.php；未配置时前台请求低频兜底也能生效，但精度较低。

缤纷云存储如何使用？ 在后台启用缤纷云存储插件，填写 endpoint / accessKey / secretKey / bucket 即可，媒体上传自动存入云端。publicUrl 留空时自动用 endpoint 拼接。

如何添加社区或私有应用源？ 在站点设置的应用商店地址处填写，应用源需遵循 runtime-store/v1 JSON 协议。