# DBErp Nginx 伪静态（重写规则）

本文只说明 **DBErp 自身** 在 Nginx 里需要的前端路由重写，便于你把规则合并进已有站点配置。  
SSL、PHP-FPM、`fastcgi_pass`、日志等请按你的环境自行配置，不在此重复。

## 前提

| 项 | 要求 |
| --- | --- |
| Web 根目录 | 必须指向 DBErp 的 **`public`** 目录，不能指到仓库根目录 |
| PHP | 8.3+，并已配置好 `location ~ \.php$`（或等价 FastCGI） |
| 对照 | Apache 用户可直接使用仓库内 **`public/.htaccess`**，无需改 Nginx |

管理端默认整域为 Filament；可选环境变量 `DBERP_ADMIN_PANEL_PATH` 将后台挂在子路径（如 `/dberp`）。**子路径部署时仍使用下面同一套 `location` 规则**，路径前缀由 Laravel 处理，不必为子路径单独写一套 Nginx 规则。

## 需要配置的规则（复制到 `server { }` 内）

将下列 `location` 放在你的 `server` 块中，且 **`root` 已指向 `.../DBErp/public`**。  
建议放在 `location ~ \.php$` **之前**（`^~` 前缀的 `location` 会优先于正则匹配）。

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

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

location ^~ /private-storage/ {
    try_files $uri /index.php?$query_string;
}
```

同目录下的 **`nginx.rewrite.conf`** 为上述片段的纯文本副本，便于直接 `include` 或复制。

### 各条规则作用

| 规则 | 作用 |
| --- | --- |
| `location /` | Laravel 前端控制器：静态文件存在则直接返回，否则交给 `index.php`（路由、Filament 页面、`/install` 等） |
| `location ^~ /livewire` | Livewire 4 更新、上传等请求走 `index.php`，避免被其它 `location` 误匹配 |
| `location ^~ /private-storage/` | 私有附件签名 URL 由应用校验后输出，与 `public/.htaccess` 中 `private-storage` 规则一致 |

## 配置步骤示例

1. 打开站点对应的 Nginx 配置（如 `/etc/nginx/sites-available/dberp.conf`）。
2. 确认 `root` 例如：

   ```nginx
   root /var/www/DBErp/public;
   index index.php;
   ```

3. 在 `server { }` 内粘贴上一节的三个 `location`（或 `include /var/www/DBErp/nginx.rewrite.conf;`）。
4. 保留你环境中已有的 PHP 处理块，例如：

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

5. 检查并重载：

   ```bash
   nginx -t && nginx -s reload
   ```

## 可选：站点校验 JSON

若使用 DBErp 站点访问校验，应用可能写入 `public/.well-known/dberp-site-verification.json`。需要保证该路径可访问时，可增加（非必须）：

```nginx
location = /.well-known/dberp-site-verification.json {
    try_files $uri /index.php?$query_string;
}
```

## 验证是否生效

1. 访问站点根路径（或你配置的 `DBERP_ADMIN_PANEL_PATH`），应出现 **登录页**，而不是目录列表或 404。
2. 登录后打开任意 Filament 列表/表单，操作不应出现 Livewire 404；浏览器网络里 Livewire 组件更新请求（Livewire 4 多为 `livewire-xxxxxxxx/update`，Livewire 3 为 `livewire/update`）应为 **200**。
3. 在系统内打开带 **私有附件** 的单据，附件链接应能正常打开（走 `/private-storage/...`）。

若静态资源 404 但 PHP 正常，多半是 `root` 未指向 `public`；若 Livewire 报错，检查是否遗漏 `location ^~ /livewire`（该前缀可匹配 `livewire-*` 与 `livewire/` 下所有路径）。

## 常见问题

**Q：只有这三条 `location` 就够了吗？**  
A：本文只覆盖 DBErp 业务相关的伪静态重写。HTTPS 证书、PHP-FPM 连接、`client_max_body_size`、静态资源缓存等仍需在你的 `server` 块中按环境自行配置。

**Q：子路径部署（`DBERP_ADMIN_PANEL_PATH=dberp`）要改成 `/dberp/livewire` 吗？**  
A：不需要。请求 URI 仍以站点根为基准，Laravel 会识别面板前缀。

**Q：Apache / 集成环境（WAMP、Herd）还要配吗？**  
A：Apache 使用 **`public/.htaccess`** 即可；Herd、Valet 等已按 Laravel 将 Web 根指向 `public` 时，通常无需再手写 Nginx。

## 相关文件

| 文件 | 说明 |
| --- | --- |
| `nginx.rewrite.conf` | 仅 DBErp 重写片段（可复制或 `include`） |
| `public/.htaccess` | Apache 等价规则 |
