安装与部署

从零把 YeCha 跑起来。当前对应内核 1.2.5;装完请接着看快速开始。

本页导航

环境要求

项目要求
PHP8.1+(推荐 8.3);扩展 pdo_mysql、mbstring、curl、simplexml、fileinfo、zip、openssl
数据库MySQL 5.7+ 或 MariaDB 10.3+,字符集 utf8mb4 / utf8mb4_unicode_ci
Web 服务器Nginx 1.20+ 或 Apache 2.4+,需可配伪静态
目录可写uploads/、var/cache/、var/home-static/
可选HTTPS 证书、CDN、Redis / OPcache(性能相关见运维)
表结构由 install/schema.sql 建立,占位符 {PREFIX} 会被安装向导替换为 config.inc.php 里的 DB_PREFIX。

安装步骤

  1. 取包:在下载中心取完整包或安装包,解压到站点根目录(docroot),确认 index.php、core/、themes/、plugins/ 在同一层。
  2. 建库:
CREATE DATABASE yecha DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yecha'@'127.0.0.1' IDENTIFIED BY '换成强密码';
GRANT ALL ON yecha.* TO 'yecha'@'127.0.0.1';
FLUSH PRIVILEGES;
  1. 配置:复制 config.inc.php.example 为 config.inc.php,填写以下常量(完整字段见配置项):
define('DB_HOST', '127.0.0.1');
define('DB_PORT', '3306');
define('DB_NAME', 'yecha');
define('DB_USER', 'yecha');
define('DB_PASS', 'CHANGE_ME');
define('DB_PREFIX', 'ye_');
define('SECRET', 'replace-with-random-64-hex');
define('TZ', 'Asia/Shanghai');
define('SITE_LANG', 'zh_CN');
define('DEBUG', false);
  1. 安装向导:浏览器打开站点根目录,按提示完成一次性安装(建表 + 建管理员)。已手工建表时访问 /install/ 会提示「已安装」。也可在 CLI 执行 php tools/upgrade.php --component core 应用待执行迁移。
  2. 配置伪静态(见下节),nginx -t && nginx -s reload。
  3. 首次安全加固(见加固),然后访问 /admin/ 登录。

Web 服务器配置

Nginx(最小可用)

server {
    listen 80;
    server_name example.com;
    root /www/wwwroot/yecha.org;
    index index.php;

    location / { try_files $uri $uri/ /index.php?$query_string; }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ ^/(var|data|tools|tests|core|config\.inc\.php) { deny all; }
    location ~* \.(bak|orig|old|save|swp|tmp|sql|gz|log)$ { deny all; }
}

注意:安装阶段不要把 install 一起 deny 掉;装完再单独锁死。伪静态关闭时系统支持 ?r=… 通道,由 index.php 转译后交给 Router。

Apache

<Directory "/www/wwwroot/yecha.org">
    AllowOverride All
    Require all granted
</Directory>

.htaccess 把所有非文件请求重写到 index.php;同时禁止直接访问 core/、var/、config.inc.php。

目录权限

chown -R www:www /www/wwwroot/yecha.org
find /www/wwwroot/yecha.org -type d -exec chmod 755 {} \;
find /www/wwwroot/yecha.org -type f -exec chmod 644 {} \;
chmod 640 /www/wwwroot/yecha.org/config.inc.php
chmod -R 775 /www/wwwroot/yecha.org/uploads /www/wwwroot/yecha.org/var

config.inc.php 含 SECRET 与数据库口令,不要放进版本库,也不要给 Web 用户写权限。

HTTPS 与 CDN

  • 全站启用 HTTPS,site.url / 站点域名与实际访问域名保持一致;反向代理下需 fastcgi_param HTTPS on,否则后台登录会话可能被判为不安全而反复跳回登录页。
  • 前面挂 CDN 时,取真实访客 IP 需在 Web 层读取代理传递的 IP 头并交给 PHP(REMOTE_ADDR),统计、限流、评论防骚扰都依赖它。
  • 证书链要完整(含中间证书),避免部分客户端握手失败。

首次安全加固

  1. 立刻修改管理员口令(后台「用户」)。
  2. 删除或锁死 install/ 目录;确认 /core/…、/var/…、/config.inc.php 直出返回 403。
  3. DEBUG 必须为 false;仅本机排错时临时打开,完事立即关掉。
  4. SECRET 用 64 位随机串生成并离线备份:换掉会让已加密的密钥(AI Key 等)失效。
  5. 数据库账号只授权本站库;备份文件不放 docroot。

验证清单

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/admin/
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/sitemap.xml
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/feed
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/healthz

清单:首页/后台/sitemap/feed/healthz 均正常;后台能登录并保存设置;上传一张附件成功;/core/version.php 直接访问被拒。

常见安装错误

现象原因处理
/install/ 返回 403拒绝规则把安装目录也拦了安装阶段把 install 从 deny 规则拆出,不要加 ^~
整站 500:Unknown column 'c.words'老库缺 ye_contents.wordsALTER TABLE ye_contents ADD COLUMN words INT UNSIGNED NOT NULL DEFAULT 0; 再回填 CHAR_LENGTH(content)
首页空白 / 模板不存在主题缺 views/layout.php后台切回默认主题 yecha,或补齐模板
后台正常、前台文章 404伪静态未生效按Nginx 配置修正并重载
上传附件失败uploads/ 不可写按目录权限修正属主
登录后立刻跳回登录页HTTPS 判定 / Cookie 域名不一致检查 fastcgi_param HTTPS on、站点域名,清一次浏览器 Cookie
数据库连接失败常量或授权不对用 mysql -h127.0.0.1 -uyecha -p yecha 实测后再写回配置

更多见常见问题与运维。