配置说明

纸鱼博客的配置分为两部分：

• 核心配置：runtime/config.php，用于数据库、站点地址、伪静态和运行环境。安装向导会写入此文件；根目录 config.php 只为旧站兼容保留。

• 站点设置：登录后台后进入“站点设置”，用于评论、上传、注册、邮件、API 等日常选项。邮件（SMTP）只在后台配置，runtime/config.php 中的 smtp 键不会被读取。

编辑核心配置

当前版本使用 runtime/config.php。手动部署时，将 config.example.php 复制到 runtime/config.php 后修改；安装向导也会自动在此处生成配置。

修改前请先备份文件。配置文件必须返回一个 PHP 数组：

<?php
return [
    'db' => [
        'host' => '127.0.0.1',
        'port' => 3306,
        'database' => 'pafish',
        'username' => '数据库用户名',
        'password' => '数据库密码',
        'charset' => 'utf8mb4',
    ],
    'auth_secret' => '请使用随机长字符串',
    'site_url' => 'https://example.com',
    'pretty_urls' => true,
    'trusted_proxies' => [],
    'debug' => false,
    'timezone' => 'Asia/Shanghai',
];

配置项

db 数据库连接

数据库信息错误时，站点无法启动或无法读取内容。修改后请确认数据库用户拥有该数据库的读写权限。

auth_secret 会话密钥

用于登录会话和安全签名。安装向导会自动生成，生产环境不要使用示例值，也不要在多个站点之间共用。

如果更换该值，现有登录会话会失效，用户需要重新登录。

site_url 站点地址

填写站点的完整地址，例如 https://example.com。结尾不要添加 /。

该地址用于生成 RSS、sitemap、Open Graph 和其他绝对链接。更换域名或启用 HTTPS 后，请同步修改此项。

pretty_urls 伪静态

• true：使用 /post/article-slug 形式的链接，要求 Nginx 或 Apache 已配置伪静态。

• false：使用 /index.php?p=post/article-slug 形式的链接，不需要伪静态规则。

伪静态规则必须把不存在的 URL 交给项目根目录的 index.php。这也适用于插件和主题声明的自然路由。若访问首页正常但文章或扩展路由返回 404，请先检查服务器规则，或暂时改为 false 验证站点功能。详细示例见安装说明和宝塔 Nginx 配置。

trusted_proxies 可信反向代理

默认值为 []，即不接受客户端自带的 X-Forwarded-For 等转发头。只有当站点确实部署在 Nginx、CDN 或负载均衡之后，且这些代理会改写转发头时，才填写实际连接 PHP 的代理 IP 或 CIDR，例如 ['127.0.0.1', '10.0.0.0/8']。

该配置影响评论、文章互动和 API 限流中“真实客户端 IP”的判定。填得过宽（例如直接写整个内网或 *）会让访客可以伪造 IP，反而削弱限流和黑名单。

debug 调试模式

• false：生产环境推荐值，不向访客显示详细错误。

• true：开发和排错时使用，会输出更详细的错误信息。

调试完成后请立即改回 false，避免数据库连接信息或文件路径暴露给访客。

timezone 站点时区

填写 PHP 支持的时区标识，例如 Asia/Shanghai。该设置会影响文章发布时间、定时发布、评论时间和 API 返回的时间。

后台站点设置

以下选项不需要修改配置文件，请在后台“站点设置”中完成：

• 站点名称、副标题、SEO 描述和 ICP 备案号

• 评论开关、评论审核、游客验证码和 IP 黑名单

• 每页文章数、Markdown 原始 HTML

• 上传大小限制

• 用户注册和邮箱验证

• SMTP 邮件、评论通知（邮件只在后台配置）

• 应用商店账号令牌

• 开放 API、请求频率、CORS 和分页上限

• 文章固定链接结构和角色权限

修改后台设置后点击“保存设置”。API Key 泄露时，请在同一页面重新生成，旧 Key 会立即失效。

安全注意事项

• 不要把 runtime/config.php 或旧版根目录 config.php 提交到公开仓库。

• 不要通过网页、截图或工单公开数据库密码、SMTP 密码和 API Key。

• Nginx 请禁止直接访问 config.php、runtime/ 和 backups/。

• 修改核心配置前先备份，确认站点可以正常访问后再继续其他变更。