开发文档安装部署
安装包已内置全部依赖（vendor/），不需要 Composer、不需要 Node，解压 + 配伪静态 + 跑安装向导即可。
一、环境要求
| 项目 | 要求 | 说明 |
|---|---|---|
| PHP | 8.1 ~ 8.4（推荐 8.2） | 8.0 也可跑，但建议 8.2 以上 |
| PHP 扩展 | pdo_mysql、mbstring、gd、fileinfo、json、bcmath | 缺 gd 会导致图片上传失败、无法转 WebP |
| 数据库 | MySQL 5.7+ / 8.0 | 字符集 utf8mb4，引擎 InnoDB |
| Web 服务器 | Nginx 或 Apache | 需要支持伪静态 / rewrite |
| 磁盘 | ≥ 200MB | 程序约 11MB，其余留给上传图片 |
| 可选 | Redis | 不装也能跑，装了缓存更快 |
整站入口在 public/index.php。如果运行目录指到根目录，前台会直接 403 或列出文件列表，后台也打不开——这是安装失败最常见的原因。
二、宝塔面板部署（推荐）
步骤 1：建站
宝塔 → 网站 → 添加站点：填域名、选 PHP 8.2、同时创建 MySQL 数据库（记住库名/用户/密码）。
步骤 2：上传解压
把 ThinkWoCMS-vX.Y.Z.zip 上传到站点根目录（如 /www/wwwroot/yourdomain.com/）并解压。解压后根目录应该直接看到 app/、public/、config/ 这些文件夹。
如果解压出来是 /www/wwwroot/yourdomain.com/ThinkWoCMS-vX.Y.Z/public/，说明多了一层，需要把里面的内容全部剪切到上一级。
步骤 3：设置运行目录
网站设置 → 网站目录 → 运行目录选 public → 保存。
步骤 4：配置伪静态
网站设置 → 伪静态 → 粘贴下面内容（把 sock 版本号改成你实际的 PHP 版本，如 php-cgi-82.sock）：
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
# 禁止访问敏感目录（注意末尾斜杠，不能拦掉 install.php）
location ~* ^/(runtime|config|app|vendor|docs|install)/ {
deny all;
return 404;
}
location ~* \.(env|lock|sql|log|md)$ {
deny all;
return 404;
}
location ~* \.(css|js|png|jpg|jpeg|gif|webp|svg|ico|woff2?)$ {
expires 30d;
access_log off;
add_header Cache-Control "public, max-age=2592000";
}
location ~ \.php$ {
fastcgi_pass unix:/tmp/php-cgi-82.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}Apache 环境不用改配置，包里的 public/.htaccess 已自带，只要确认 mod_rewrite 已开启、AllowOverride All 即可。
步骤 5：跑安装向导
浏览器打开 http://你的域名/install.php，页面会依次让你完成：
- 环境检测：PHP 版本、扩展、目录可写、vendor 完整性，全部打勾才能继续
- 数据库配置：地址（一般
127.0.0.1）、库名、用户名、密码、表前缀（默认tw_） - 管理员账号：登录账号、密码（需二次确认，至少 6 位）、昵称
- 演示数据：建议勾选——装完直接是一个完整的外贸站（双语、16 栏目、19 条内容、3 条询盘）
点「开始安装」后会自动建表、写 .env、建目录、写 install.lock。成功页面会告诉你后台地址。
步骤 6：安装后必做 5 件事
| 动作 | 怎么做 / 为什么 |
|---|---|
| 删安装目录 | 删除 install/ 目录和 public/install.php，防止被人重装覆盖数据 |
| 改后台入口 | 把 public/admin.php 改成别人猜不到的名字，如 tw886.php，后台地址随之变化 |
| 开 HTTPS | 宝塔一键申请 Let's Encrypt 证书，强制 HTTPS（SEO 与信任度都需要） |
| 改演示内容 | 后台 → 站点设置，把公司名/电话/邮箱/地址换成自己的 |
| 设时区与备份 | 宝塔计划任务：每天 3 点备份数据库 + 网站目录 |
目录权限
只需两个目录可写，属主设为 www：
cd /www/wwwroot/yourdomain.com
chown -R www:www runtime public/uploads
chmod -R 755 runtime public/uploads三、常见错误排查
| 现象 | 原因 | 解决 |
|---|---|---|
| 访问域名显示 403 / 目录列表 | 运行目录没指向 public | 网站设置 → 网站目录 → 运行目录改 public |
| 首页能开，点内页全 404 | 伪静态没配 | 粘贴第二节的 nginx 规则并重载 |
访问 /install.php 也是 404 |
伪静态里敏感目录规则少了末尾斜杠 | 必须是 ^/(...|install)/，带斜杠才不会拦掉 install.php |
| 白屏、无任何输出 | PHP 版本太低 / 扩展缺失 / 文件没传全 | 看 runtime/log/ 下当天日志；确认 PHP ≥ 8.1、vendor 目录完整 |
| 安装时提示「数据库连接失败」 | 库名/密码错，或 127.0.0.1 不通 | 用宝塔 phpMyAdmin 验证；部分环境 host 要写 localhost |
| 装完打开首页报「表不存在」 | 表前缀填的和实际不符 | 检查 .env 里 DATABASE_PREFIX，与数据库里实际前缀一致 |
| 后台上传图片报错 | 缺 GD 或 uploads 不可写 | 宝塔装 gd 扩展；chown -R www:www public/uploads |
| 后台样式全乱（裸 HTML） | public/static 没传全 |
确认 public/static/layui/ 里 css、layui.js、font、modules 四样都在 |
| 改了内容前台没变 | 静态化缓存 | 后台右上角清缓存，或 SEO 工具里关掉静态化 |
中文站访问 /zh-cn/ 404 |
后台没添加 zh-cn 语言，或该语言栏目没建 | 语言列表里添加并启用，再给中文站建对应栏目 |
任何 500 错误，先看 runtime/log/YYYYMM/DD.log，里面会写明确的异常类与文件行号。宝塔也可以在「网站 → 错误日志」里看 nginx 层的问题。
四、旧站升级（覆盖更新）
从旧版本升到当前版本，三步，不动数据库（表结构由 Upgrade.php 在首次访问时自动补齐）：
- 备份：目录 + 数据库各打一份（见下一节命令）
- 覆盖：新包上传到网站根目录，覆盖解压。
注意 宝塔的文件管理器解压遇到同名文件可能跳过， 导致"版本号变了但功能没变"。稳妥做法：先删除要替换的目录（如app/public/static/template/），再解压。 - 清缓存：删掉
runtime/下的cache/temp/session/index/四个目录， 然后登录后台点右上角「清缓存」，前台 Ctrl+F5 强制刷新
清掉 runtime/session/ 后所有登录态失效，需重新登录后台；升级期间前台不受影响。
另外 docs/、install/、README.md 都可以只放在本地，不必上传到生产环境。
五、从测试站搬到正式站
- 打包正式站目录并导出数据库：
mysqldump -u root -p 库名 > db.sql - 新服务器建站 → 上传解压 → 改运行目录与伪静态
- 导入
db.sql，把.env里的数据库信息改成新的 - 不要复制
runtime/（里面是旧环境的缓存与编译模板） - 清空
runtime/，访问首页验证，再进后台清一次缓存
六、备份与回滚
# 代码备份
tar -czf /www/backup/site-$(date +%F).tar.gz /www/wwwroot/yourdomain.com
# 数据库备份
mysqldump -u root -p 库名 > /www/backup/db-$(date +%F).sql
# 回滚
rm -rf /www/wwwroot/yourdomain.com
tar -xzf /www/backup/site-2026-11-02.tar.gz -C /www/wwwroot/
mysql -u root -p 库名 < /www/backup/db-2026-11-02.sql框架与 LayUI 的升级方式见 SEO 运维 里的「版本与升级」小节。