ny-exam-platform/docs/guide/install.md

环境要求与部署

环境要求

项目	要求	说明
PHP	≥ 8.0	推荐 8.1+
curl	必需	调用卷王 API
json / mbstring	必需	数据编解码、中文处理
openssl	推荐	登录时对密码做 RSA 加密；缺失时降级为明文提交
zip	可选	缺失时用内置解析器读取 xlsx（写入 xlsx 内置实现无需此扩展）
pdo_sqlite	推荐	启用 SQLite 存储；缺失时自动降级为 JSON 文件存储
数据库	无	不需要 MySQL / PostgreSQL
Composer	无	没有任何第三方依赖

用 php -m 可以查看已加载的扩展。

部署方式

方式一：PHP 内置服务器（体验 / 内网临时使用）

cd ny-exam-platform
php -S 0.0.0.0:8080

浏览器打开 http://localhost:8080。Windows 下也可双击 启动平台.bat。

::: warning 仅用于内网体验 PHP 内置服务器是单进程、无并发能力的开发服务器，不要用于生产。 并且它不解析 .htaccess，data/ 目录会可被直接访问，请务必参考 安全加固清单。 :::

方式二：Nginx + PHP-FPM（推荐生产）

假设站点根目录为 /www/sites/sj.exam.nxxy335.top/index，那么把仓库内容放在该目录下即可。

server {
    listen 80;
    server_name sj.example.com;
    root /www/sites/sj.exam.nxxy335.top/index;
    index index.php index.html;

    charset utf-8;
    client_max_body_size 20m;   # 名单文件导入上限，与后端 20MB 校验一致

    # ---- 安全：禁止直接访问数据目录（nginx 不读 .htaccess，必须显式配置）----
    location ^~ /data/ {
        deny all;
        return 404;
    }

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

    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        include        fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # 不要暴露隐藏文件
    location ~ /\. {
        deny all;
        return 404;
    }
}

校验并重载：

nginx -t && nginx -s reload

方式三：Apache

仓库会在 data/ 及其子目录自动生成 .htaccess（内容 Deny from all）， Apache 下 data/ 默认即被保护。仍需确认：

• 虚拟主机 AllowOverride 不为 None（否则 .htaccess 被忽略）；
• mod_rewrite 若启用，确认没有规则把 /data/ 放行。

方式四：宝塔面板

1. 新建站点 → 根目录指向仓库目录；
2. PHP 版本选 8.0+，安装 fileinfo、opcache（可选）；
3. 站点 → 配置文件，在 server {} 内加入上面的 location ^~ /data/ 段；
4. 站点 → 目录权限，确保 data/ 可写（运行用户通常为 www）；
5. 若使用反向代理，确认 /api.php 的 action 参数未被缓存。

目录权限

路径	需要	说明
data/	可写	配置、名单、令牌、快照的根目录
data/ny.db	可写	SQLite 主库（启用 pdo_sqlite 时）
data/uploads/	可写	导入名单时的临时落盘，解析后立即删除
data/cache/	可写	卷王令牌缓存、结果缓存
data/snapshots/	可写	成绩快照

chown -R www:www data
chmod -R 755 data

Windows 下给 IIS_IUSRS 或站点应用程序池身份赋予 data 的「修改」权限。

升级

仓库是纯文件部署，升级即覆盖文件：

git pull

覆盖后 data/ 保留（其中存放配置与名单，并且在 .gitignore 中）， 程序会在首次访问时自动完成目录初始化与数据迁移。

::: tip 关于 SQLite 迁移 首次在有 pdo_sqlite 的环境运行时，data/config.json 与 data/roster.json 会被自动迁移进 data/ny.db，之后以数据库为准，文件作为备份继续双写。 迁移是幂等的，重复执行不会覆盖已入库的数据。 :::

下一步

• 快速上手
• 安全加固清单