从零把 YeCha 跑起来。当前对应内核 1.2.5;装完请接着看快速开始。
本页导航
环境要求
| 项目 | 要求 |
|---|---|
| PHP | 8.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。
安装步骤
- 取包:在下载中心取完整包或安装包,解压到站点根目录(docroot),确认
index.php、core/、themes/、plugins/在同一层。 - 建库:
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;- 配置:复制
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);- 安装向导:浏览器打开站点根目录,按提示完成一次性安装(建表 + 建管理员)。已手工建表时访问
/install/会提示「已安装」。也可在 CLI 执行php tools/upgrade.php --component core应用待执行迁移。 - 配置伪静态(见下节),
nginx -t && nginx -s reload。 - 首次安全加固(见加固),然后访问
/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/varconfig.inc.php 含 SECRET 与数据库口令,不要放进版本库,也不要给 Web 用户写权限。
HTTPS 与 CDN
- 全站启用 HTTPS,
site.url/ 站点域名与实际访问域名保持一致;反向代理下需fastcgi_param HTTPS on,否则后台登录会话可能被判为不安全而反复跳回登录页。 - 前面挂 CDN 时,取真实访客 IP 需在 Web 层读取代理传递的 IP 头并交给 PHP(
REMOTE_ADDR),统计、限流、评论防骚扰都依赖它。 - 证书链要完整(含中间证书),避免部分客户端握手失败。
首次安全加固
- 立刻修改管理员口令(后台「用户」)。
- 删除或锁死
install/目录;确认/core/…、/var/…、/config.inc.php直出返回 403。 DEBUG必须为false;仅本机排错时临时打开,完事立即关掉。SECRET用 64 位随机串生成并离线备份:换掉会让已加密的密钥(AI Key 等)失效。- 数据库账号只授权本站库;备份文件不放 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.words | ALTER 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 实测后再写回配置 |