入门

安装与部署

按真实的部署顺序走一遍：先备好 PHP、MySQL、Redis，再把服务跑起来，然后用浏览器完成安装向导，最后重启服务并自检。服务器上不需要 Node、npm 或 composer。

第一步：准备环境

整个过程分五步——准备环境 → 起服务 → 走安装向导 → 重启服务 → 安装后自检。安装向导本身就是这套服务提供的网页，所以顺序不能颠倒：服务没跑起来，向导也打不开。

组件	要求	说明
PHP	≥ 8.1	低于 8.1 环境检测直接判未通过；Docker 参考配置用的是 8.3
MySQL	5.7 或 8.0+	字符集固定 utf8mb4、collation 固定 `utf8mb4_general_ci`；两个大版本都兼容
Redis	必需	缓存、队列、登录限流与幂等都靠它；生产环境 Redis 不可用时服务会 fail-closed 进入维护保护，而不是带病运行
操作系统	Linux（生产）/ Windows（开发）	Linux 才有平滑重载；Windows 下重启服务要手动关掉再重开

PHP 扩展

扩展	是否必需	用途
`pdo_mysql`	必需	连接数据库
`json`	必需	接口数据编解码
`mbstring`	必需	中文等多字节文本处理
`openssl`	必需	加密与 HTTPS 调用
`curl`	必需	调用微信、支付等外部服务
`fileinfo`	必需	上传文件的类型识别
`redis`	必需	缓存、队列、登录限流
`zip`	可选	解包应用安装包（`.tzapp`）。缺了装不了任何应用——虽然不挡安装，强烈建议装上
`sodium`	可选	校验安装包与授权文件的签名；缺失时带签名的应用包装不上

目录写权限

runtime——运行期文件，需要连子目录一起可写。
public/uploads——上传的图片与附件，需要连子目录一起可写。
程序根目录——安装时要在这里写出 .env 和 install.lock。

环境检测会把「目录还没建」和「目录建了但当前运行 PHP 的系统用户写不了」分成两种结果报出来，并直接给出可以照抄的 mkdir -p / chown / chmod 命令——按提示做完再点「重新检测」即可。

第二步：把服务跑起来

在 server/ 目录下执行

$ php start.php start # Linux 前台运行（调试用）

$ php start.php start -d # Linux 守护进程运行（生产）

$ php start.php reload # 平滑重载（不断连接）

$ php start.php stop # 停止

$ php windows.php # Windows 开发环境启动

$ php supervisor.php # 受管模式：崩溃自动拉起 + 升级时优雅重启

默认监听 0.0.0.0:8787；生产环境请在前面加一层 Nginx / Caddy 反向代理并终结 HTTPS。
HTTP 进程数由 HTTP_COUNT 控制，不填时按 CPU 核数 × 2 计算（取不到核数时退回 4）。
队列消费与定时任务是独立的常驻进程，随主进程一起拉起，不需要单独部署或配置系统 cron。

用 Docker Compose 起服务（可选）

框架附带一份 Docker 参考配置：php:8.3-cli 基础镜像 + MySQL 8.0 + Redis 7 三个服务编排。镜像里只有 PHP 运行时与扩展，代码以挂载方式进入容器——改代码重启容器就生效，不用重建镜像。

参考流程

$ docker compose up -d

# 三个容器起来后，等 mysql 的健康检查通过

# 再用浏览器打开 8787 端口上的 /install 走安装向导

MySQL 容器要显式指定 --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci（参考配置里已经带了）。
服务容器的健康检查探测的是 8787 端口。参考配置不往宿主机发布端口、只挂在反向代理网络上——要打开向导，得先给自己留一条访问路径（临时加端口映射，或让反代把 /install 转进来）。
经反向代理访问 /install 就不算「直接本机」了，必须先配好下面讲的 INSTALL_SETUP_SECRET。
容器化部署下的「重启服务」就是重启对应容器，不用进容器敲命令。

第三步：走安装向导

服务起来后，浏览器访问 /install。左侧是五步进度：环境检测 → 数据库 → Redis → 管理员 → 完成。如果这套部署已经装过，页面会直接显示「系统已安装」，并列出版本、安装时间、表前缀与部署 ID。

1
环境检测
自动跑一遍 PHP 版本、扩展与目录写权限。未通过的项会被置顶，每项都带着「下一步该干什么」的说明。修好后点「重新检测」——全部通过时按钮才会变成「下一步」。
2
数据库
填 MySQL 连接（默认 127.0.0.1:3306，库名 tenraft，用户 root，表前缀 tf_）。库名只允许字母数字下划线，表前缀只允许小写字母数字下划线。库不存在会自动创建，字符集固定 utf8mb4。必须先点「测试连接」并成功，「下一步」才会亮。
3
Redis
填 Redis 连接（默认 127.0.0.1:6379，密码可空，库序号只支持 0–15）。同样要先测试连接成功才能继续。
4
管理员
创建拥有最高权限的平台超级管理员：用户名 3–32 位字母、数字或下划线；密码至少 12 位，且 UTF-8 编码后不超过 72 字节；还要再输一遍确认。昵称可留空。
5
完成
点「开始安装」后由服务端一口气做完：生成加密密钥与部署标识 → 原子写入 .env → 用新配置连库建表 → 写入基础配置、核心菜单、示例站点、内置定时任务与功能开关注册表 → 写出 install.lock。页面会显示执行了多少个迁移、管理员 ID 与部署 ID。

第四步：重启服务，再登录

数据表和管理员账号建好了，但服务进程仍在用安装前的配置运行——它启动时还没有数据库连接信息。所以装完必须让服务换上新配置，后台才登得进去。向导会先尝试自动完成这件事：

运行方式	会发生什么	你要做的
Linux 直接启动	向导自动发平滑重载信号，进程依次换新、零停机；页面直接显示「安装完成」	什么都不用做，点「进入平台后台」
Windows 开发环境	无法自动重载；页面显示「安装完成，还差一步：重启服务」	关掉正在运行的 `php windows.php` 窗口，重新执行一次
Docker / systemd 托管	Linux 容器同样能收到重载信号，多数情况下也是自动完成；发不出信号时页面才提示需要重启	只有看到提示时才动手：重启对应的容器或系统服务

重启完点页面上的「我已重启，检测服务状态」。它会连采几次健康检查再下结论——多进程部署里，执行安装的那个进程本身已经持有新配置，只测一次会误判成功。检测通过后页面才切换到「安装完成」。

.env 关键配置

配置项	说明
`APP_ENV`	生产写 `production`；`local` 等开发环境会放宽扩展包验签、Redis 故障也不熔断
`APP_KEY`	32 字节加密密钥，安装时自动生成——丢了就再也解不开已存储的支付凭证等密文
`INSTALL_ID`	部署唯一标识；多套部署共用一个 Redis 时靠它隔离键名
`HTTP_PORT` / `HTTP_COUNT`	监听端口（默认 8787）/ HTTP 进程数（留空 = CPU × 2）
`DB_` / `REDIS_`	数据库与 Redis 连接，由安装向导写入
`INSTALL_SETUP_SECRET`	远程安装密钥，长度须 ≥ 24 位；只在安装阶段用得到
`EXTENSION_VERIFY_SIGNATURE` / `EXTENSION_OFFICIAL_PUBKEY_FILE`	应用包验签开关与公钥文件路径。生产默认强制验签，公钥留空时应用安装会明确拒绝
`PLATFORM_RESERVED_DOMAINS`	平台自用的保留域名，租户站点不得绑定这些根域及其子域
`TRUSTED_PROXIES`	可信代理网段（CIDR，逗号分隔）。留空即默认信任回环与全部私有网段，够用于 Docker、内网与常见负载均衡；只有反代落在公网地址上时才需要填
`PAY_RETURN_ORIGINS`	H5 支付同步回跳允许的前端来源；站点已验证的自有域名会自动加入
`MAINTENANCE_FILE`	维护状态文件路径；多节点部署建议指向各节点共同挂载的绝对路径

第五步：安装后自检

1访问 GET /health，确认 installed 为真，且 db / redis / queue 三项都是 ok——装之前它们是 not_configured，还显示 not_configured 就说明服务没重启成功。
2看一眼同一份结果里的 disk：剩余空间低于 200 MB 会判 fail，整体状态随之变成 degraded。
3浏览器打开 /admin/，用刚创建的管理员账号登录平台后台。
4进「系统 → 进程管理」，确认 HTTP、队列消费、定时调度三类进程都有心跳。这一页每 5 秒刷新一次，右上角的「平滑重启」按钮可以让全部进程依次重启（仅 Linux 支持）。

自检通过之后，新装的系统里只有一个可以删掉的示例站点。想让它真正能开张，按下面三步走：

1
装应用
进「产品 → 应用商店」，装上随框架一起发布的官方应用（商城、表单、AI 等）。没有应用时，站点后台只有会员与资金这些基础能力。
2
创建第一个租户
在「客户 → 租户管理」新建租户，并在「名额管理」给它划拨应用名额。租户拿到名额，才能把应用绑到自己的站点上。
3
为租户创建站点
在「客户 → 站点管理」为该租户新建站点，绑定应用后就能进入站点后台开始配置和经营。