OSSN 10.1 配置参数详解

目标：把 OSSN 10.1 的全部可配置面讲透——它没有集中的 config.yaml，参数散落在三层：安装目录下的 configurations/ 三个 PHP 文件（文件层）、数据库 ossn_site_settings 表 14 个设置项（站点层）、安装器生成的 .user.ini / .htaccess（PHP 运行时层）。本文逐参数给出含义、默认值、修改方式与代码依据，并提供生产配置模板与排障实录。全部参数值与命令回显取自 10.1 实装站点（PHP 8.2.35 + MySQL 8.0.46，2026-11-02）。

一、环境信息

• OSSN：10.1（ossn_site_settings 表 site_version 实测值 10.1）
• PHP：8.2.35（php -r 'echo PHP_VERSION;' 实测回显 8.2.35）
• MySQL：8.0.46（mysql --version 实测回显 mysql Ver 8.0.46 for Linux on x86_64 (MySQL Community Server - GPL)）
• 站点根目录：/var/www/html（Apache DocumentRoot，站点 URL http://127.0.0.1:8139/）
• 配置目录：/var/www/html/configurations/
• 用户数据目录：/var/www/ossn_data/（位于安装目录之外）
• 后台入口：/administrator；演示管理员 admin / q1w2e3r4
• 部署过程：见《OSSN 10.1 Docker Compose 部署指南》；选型背景见《OSSN 介绍与选型指南》

二、前置条件

• 对 /var/www/html/configurations/ 有写权限的账号（root 或 sudo -u www-data）；
• php 命令行可用（改完配置文件用 php -l 做语法自检）；
• mysql 客户端可连站点库（本文示例：mysql -uossn -pq1w2e3r4 ossn）；
• 已按官方路径完成安装（configurations/ 下已存在 ossn.config.db.php 与 ossn.config.site.php——这两个文件是安装器生成的，不存在时站点会直接跳转安装器）。

三、参数查看与修改方式

OSSN 参数分三层，修改方式与生效机制各不相同：

① 文件层（configurations/ 三件套）

ls -la /var/www/html/configurations/

实测回显（安装完成后）：

classes.php
libraries.php
ossn.config.db.example.php
ossn.config.dcache.php
ossn.config.db.php
ossn.config.site.example.php
ossn.config.site.php

ossn.config.db.php、ossn.config.site.php 由安装器从同名 .example.php 模板做占位符替换生成（configurations_db()/configurations_site()，占位符为 <<host>> <<port>> <<user>> <<password>> <<dbname>> 与 <<siteurl>> <<datadir>>）；ossn.config.dcache.php 随包发布、默认 disabled，ACP 动态缓存页保存时会整体回写该文件。修改方式：直接 vim 编辑，PHP 每个请求都重新 include，无需任何 reload/restart 即生效；改完务必 php -l <文件> 自检（这是普通 PHP 文件，语法错误会白屏全站）。

② 站点层（数据库 ossn_site_settings 表）

mysql -uossn -pq1w2e3r4 ossn -e "SELECT * FROM ossn_site_settings;"

实测回显（安装并浏览后 14 行）：

setting_id	name	value
1	theme	goblue
2	site_name	OSSN Demo
3	language	en
4	cache	1
5	owner_email	admin@quzuo.net
6	notification_email	noreply@quzuo.net
7	upgrades	["1632413382.php","1633420776.php","1655424000.php","1655453491.php","1659870406.php","1669507200.php","1669852800.php","1680051600.php","1694649600.php","1697828400.php","1710633600.php","1710892800.php","1711411200.php","1712361600.php","1738108800.php","1738148400.php","1758122441.php","1758132878.php","1758187205.php","1758208966.php","1758280345.php","1759406138.php","1760034093.php","1760113687.php","1772616946.php","1772642541.php","1772696802.php","1772721318.php","1773864888.php","1776753402.php","1780131275.php","1780222007.php","1780247819.php","1780771622.php","1782450889.php","1782934787.php","1785167778.php","1790854847.php"]
9	display_errors	off
10	site_key	86a9538e
11	last_cache	1793608047
12	site_version	10.1
13	notification_name	OSSN Demo
14	copyrights	OSSN Demo

修改方式首推后台 ACP（/administrator → Settings 各页），代码路径统一走 OssnSite::setSetting()；数据库直改可行但绕过配套逻辑（如 cache 行变更要同步重建缓存文件），仅排障时使用。

③ PHP 运行时层（安装器生成的两个派生文件）

站点根目录的 .user.ini（安装器从 installation/configs/user.ini.dist 生成，PHP-FPM 场景生效）与 .htaccess 中的 <IfModule mod_php.c> php_value 块（mod_php 场景生效），内容实测回显：

post_max_size=105M
upload_max_filesize=100M
memory_limit=512M
register_globals=0
default_charset="utf-8"
allow_url_fopen=on

修改方式：编辑这两个派生文件本身（.htaccess 注意首行校验和——安装器每次加载安装页会比对首行，手改首行注释会导致被重写回模板）。

四、参数总览

五、核心参数分类详解

5.1 数据库连接（ossn.config.db.php，5 参数）

实测生成全文：

$Ossn->host = 'db';
$Ossn->port = '3306';
$Ossn->user = 'ossn';
$Ossn->password = 'q1w2e3r4';
$Ossn->database = 'ossn';

• host/port：安装表单 dbhost 字段支持 主机:端口 写法——OssnInstallation::dbhost() 用正则 ([\w\.-]+)(|\:(\d+))$ 拆分，未带端口时取 ini_get('mysqli.default_port')，仍为空则回退 3306；
• user/password/database：直填 mysqli 连接；连接失败抛 DatabaseException（全站白屏级错误）；
• 口令为明文存储，这是 OSSN 的既定设计（同 wp-config.php 逻辑），缓解手段是文件权限（见 6.2 模板与 7.3）；
• 换库/改口令：同步改本文件 + 数据库侧授权，无需重启 Web（每请求 include）。

5.2 站点 URL 与数据目录（ossn.config.site.php，2 参数）

实测生成全文：

$Ossn->url = 'http://127.0.0.1:8139/';
$Ossn->userdata = '/var/www/ossn_data/';

• url：所有资源链接、回调、邮件内链的基址，必须以 / 结尾（安装器表单 hidden 字段 url 的值即带尾斜杠，来自 OssnInstallation::url()）；换域名/上 HTTPS 时改这里，同时更新站点层 notification_email 域名与 Web 服务器证书；
• userdata：用户上传文件、CLI 记账、组件缓存的根目录。安装器有两条硬校验（OssnInstallation::INSTALL()）：数据目录不能位于安装目录内（stripos($this->datadir, ossnInstallationDir()) === 0 即拒绝，报 "data:directory:outside"）；写入测试文件 writeable 必须成功，否则报 "data:directory:invalid"。默认值由 DefaultDataDir() 算出——安装目录的上级目录下的 ossn_data/（站点根为 /var/www/html 时即 /var/www/ossn_data/）。

5.3 站点设置表（ossn_site_settings，14 项）

（setting_id=8 在实测表中缺号——安装 SQL 的固定编号序列，属正常现象。）

5.4 动态缓存（ossn.config.dcache.php，7 键）

随包默认全文：

$Ossn->dynamic_cache_settings = array(
		"status"   => "disabled",
		"type"     => "",
		"host"     => "",
		"port"     => "",
		"username" => "",
		"password" => "",
);

• status：disabled/enabled；type：redis 或 memcached（对应核心类 OssnRedis/OssnMemcached，消费方为 OssnDynamicCaching）；
• host/port/username/password：缓存服务器连接参数；
• 修改方式：ACP → Cache Settings → 动态缓存页（表单 admin/dynamic_cache_settings）。该页会先检测 PHP 扩展（extension_loaded('memcached'/'redis') 打勾/打叉），保存时经 actions/administrator/cache/dynamic.php 测试连接成功后用模板整体回写本文件——所以手改文件与 ACP 保存二选一，ACP 保存会覆盖手改；
• 前提：PHP 装 redis 或 memcached 扩展。实测本环境 php -m 清单中两者均无（[PHP Modules] ... sodium SPL sqlite3 standard ... 无 redis/memcached 行），故本演示站动态缓存保持 disabled，仅用文件缓存。

5.5 PHP 运行时参数（.user.ini / .htaccess）

安装器同时生成两份等价配置适配两种 SAPI：.user.ini（FPM，实测内容见第三章③）与 .htaccess 的 mod_php 块（php_value memory_limit 512M、php_value post_max_size 105M、php_value upload_max_filesize 100M、php_flag session.cookie_httponly on 等）。上传大照片报 413/超限时的调整点就在这里（100M 上限），改后重载 PHP-FPM（systemctl reload php8.2-fpm）或 Apache 使新值生效——注意 .user.ini 受 PHP max_input_time 缓存影响，默认 300 秒后才重读。

六、生产配置模板

ossn.config.db.php（生产建议独立低权账号）：

$Ossn->host = '127.0.0.1';
$Ossn->port = '3306';
$Ossn->user = 'ossn_app';
$Ossn->password = '<强口令，仅 GRANT ossn.*>';
$Ossn->database = 'ossn';

ossn.config.site.php：

$Ossn->url = 'https://sns.example.com/';   // 必须带尾斜杠
$Ossn->userdata = '/srv/ossn_data/';        // 必须在安装目录之外、www-data 可写

ossn.config.dcache.php（Redis 场景）：

$Ossn->dynamic_cache_settings = array(
		"status"   => "enabled",
		"type"     => "redis",
		"host"     => "127.0.0.1",
		"port"     => "6379",
		"username" => "",
		"password" => "<requirepass 值>",
);

上线检查清单：

php -l /var/www/html/configurations/ossn.config.db.php
php -l /var/www/html/configurations/ossn.config.site.php
chmod 640 /var/www/html/configurations/ossn.config.*.php
chown root:www-data /var/www/html/configurations/ossn.config.*.php
mysql -uossn_app -p ossn -e "SELECT name,value FROM ossn_site_settings WHERE name IN ('display_errors','cache','site_version');"

期望末条查询 display_errors=off、cache=1、site_version=10.1。

七、常见问题

7.1 改完配置文件全站白屏

三件套是普通 PHP 文件，一个引号错误即全站致命。修改流程固定为：vim → php -l → 浏览器验证。若已白屏，tail Web 服务器 error log 找到报错文件与行号修复即可；OSSN 的异常页还会给出错误编号（实测形如 #1793608859|B12D5F69125957EF2E994916C5E0ABAC），把 display_errors 打开能看到完整堆栈（见 7.4）。

7.2 数据目录装在安装目录内被拒

安装器 INSTALL() 第一步就检查 datadir 是否以安装目录为前缀，命中即报 "The data directory must be outside the installation directory"。把 datadir 指到安装目录同级或之外（默认 /var/www/ossn_data/ 即合规），已装站点改 ossn.config.site.php 的 $Ossn->userdata 同样受"目录可写"约束（写测试文件机制）。

7.3 配置文件明文口令的暴露面

.htaccess 的 RedirectMatch 404 屏蔽了 actions/、libraries/、classes/ 等目录，但未屏蔽 configurations/——好在其中 .php 文件经 HTTP 访问时只执行不输出源码（实测返回空 body）。真正的暴露面是备份归档与版本库：备份包加密、configurations/ 不入 git（.gitignore 已排除生成件），文件权限收紧到 640 root:www-data。

7.4 排障要开错误显示，生产要关

三种等价入口：ACP 设置项 display_errors；CLI php /var/www/html/system/handlers/cli --handler=DisplayErrors（实测回显绿色 Error reporting enabled!）与 --handler=DoNotDisplayErrors（回显 Errors reporting disabled）；或安装目录的 DISPLAY_ERRORS 标记文件（仅影响安装器）。生产环境保持 off——错误页会把 owner_email 与堆栈暴露给访客。

7.5 动态缓存页显示扩展未装 / 连接失败

ACP 动态缓存页的 Memcached/Redis 行打叉 = PHP 扩展缺失（extension_loaded() 检测），先 apt install php-redis（或 php-memcached）再保存；打勾但"连接测试失败"（提示 admin:dcache:errorconnection）= host/port/口令错或缓存服务未起。保存成功才会回写 ossn.config.dcache.php，失败时文件保持原样。

7.6 cache 行被误删/表重建

ossn_disable_cache()/ossn_create_cache() 对 setting_id='4' 硬编码更新，任何"清理设置表"的 SQL 操作若改变了行 id，缓存开关将静默失效（ACP 与 CLI 都报失败）。恢复方法：按第三章②的回显把 cache 行插回 setting_id=4。

八、参考链接

• OSSN 源码仓库（配置生成逻辑：installation/classes/OssnInstall.php、libraries/ossn.lib.cache.php、actions/administrator/cache/dynamic.php）：https://github.com/opensource-socialnetwork/opensource-socialnetwork
• 站内系列：《OSSN 介绍与选型指南》 、《OSSN 10.1 Docker Compose 部署指南》 、《OSSN 10.1 常用 CLI 命令与工具详解》
• 官方安装 wiki：https://www.opensource-socialnetwork.org/wiki/view/706/how-to-install-open-source-social-network
• 官方社区：https://www.opensource-socialnetwork.org/community