v1.2修复优化

2026-05-08 10:05:31 +08:00
parent 80b71a973a
commit 4cf6bd4b4b
12 changed files with 238 additions and 128 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -54,13 +54,32 @@

 ```
 ai-chat/
-├── public/                  # Web 根目录
+├── public/                  # Web 根目录（Nginx 指向此目录）
+│   ├── index.php            # 首页入口（自动路由到登录/安装页）
 │   ├── api.php              # API 统一入口（路由分发）
+│   ├── router.php           # PHP 内置开发服务器路由文件
 │   ├── login.php            # 登录页面
 │   ├── chat.php             # 聊天主页面
 │   ├── config.php           # 配置管理页面
-│   └── install.php          # 安装向导页面
-├── app/                     # 应用代码（命名空间 App\）
+│   ├── install.php          # 安装向导页面
+│   ├── assets/              # 前端静态资源
+│   │   ├── css/             # 样式文件
+│   │   │   ├── style.css    # 全局样式
+│   │   │   ├── chat.css     # 聊天界面样式
+│   │   │   └── markdown.css # Markdown 渲染样式
+│   │   ├── js/              # JavaScript
+│   │   │   ├── api.js       # API 调用封装
+│   │   │   ├── chat.js      # 聊天核心功能
+│   │   │   ├── config.js    # 配置页面逻辑
+│   │   │   ├── install.js   # 安装向导逻辑
+│   │   │   ├── login.js     # 登录页面逻辑
+│   │   │   ├── session.js   # 会话管理
+│   │   │   ├── upload.js    # 文件上传
+│   │   │   ├── markdown.js  # Markdown 渲染
+│   │   │   └── storage.js   # 本地存储
+│   │   └── img/             # 图片
+│   └── uploads/             # 用户上传文件
+├── app/                     # 应用代码（命名空间 App\，PSR-4 自动加载）
 │   ├── Config/              # 配置类
 │   │   ├── Database.php     # 数据库连接（单例 PDO）
 │   │   └── AppConfig.php    # 应用配置读写
@@ -95,21 +114,7 @@ ai-chat/
 │       └── layout/
 │           ├── header.php
 │           └── footer.php
-├── assets/                  # 前端静态资源
-│   ├── css/                 # 样式
-│   │   ├── style.css        # 全局样式
-│   │   ├── chat.css         # 聊天界面样式
-│   │   └── markdown.css     # Markdown 渲染样式
-│   ├── js/                  # JavaScript
-│   │   ├── api.js           # API 调用封装
-│   │   ├── chat.js          # 聊天核心功能
-│   │   ├── session.js       # 会话管理
-│   │   ├── upload.js        # 文件上传
-│   │   ├── markdown.js      # Markdown 渲染
-│   │   └── storage.js       # 本地存储
-│   └── img/                 # 图片
-├── config/                  # JSON 配置文件
-├── uploads/                 # 用户上传文件
+├── config/                  # JSON 配置文件（安装后生成）
 ├── docs/                    # 文档
 └── composer.json            # Composer 配置
 ```
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -14,7 +14,7 @@
 1. 网站 → 添加站点
 2. 填写域名
 3. PHP 版本选择 **PHP 8.0**
-4. 数据库选择"不创建"
+4. 数据库选择"不创建"（安装向导会连接你手动创建的数据库）

 ### 3. 部署代码

@@ -31,30 +31,65 @@ chmod -R 755 .
 chown -R www:www .
 ```

-### 5. 配置 Nginx
+### 5. 配置伪静态

 1. 站点设置 → 网站目录 → 运行目录改为 `/public`
-2. 站点设置 → 配置文件 → 添加 `docs/baota-nginx-snippet.conf` 中的配置
+2. 站点设置 → **伪静态** → 将 `docs/baota-nginx-snippet.conf` 的内容粘贴进去，保存

-### 6. 运行安装向导
+> 注意：是粘贴到"伪静态"输入框，不是"配置文件"。
+> 如 PHP 版本不是 8.0，需将 `php-cgi-80` 改为对应版本号（如 `php-cgi-81`）。

-访问 `http://your-domain.com/install.php`
+### 6. 创建数据库

-### 7. SSL 配置（可选）
+安装向导不会自动创建数据库，需要你提前手动创建：
+
+1. 宝塔面板 → 数据库 → 添加数据库
+2. 记录数据库名、用户名和密码，安装向导中需要填写
+
+### 7. 运行安装向导
+
+访问 `http://your-domain.com/install.php`，按步骤完成安装。
+
+### 8. SSL 配置（可选）

 站点设置 → SSL → Let's Encrypt → 申请证书

-## 手动部署
+---

-### Nginx 配置
+## 手动部署（Nginx + PHP-FPM）

-参考 `docs/nginx.conf` 文件，将 `root` 指向 `public/` 目录。
+### 1. 安装依赖

-### PHP-FPM 配置
+```bash
+composer install
+```

-确保 PHP-FPM 监听 socket 配置正确（通常为 `/tmp/php-cgi-80.sock` 或 `127.0.0.1:9000`）。
+### 2. Nginx 站点配置

-### 目录权限
+使用 `docs/nginx.conf` 作为完整的站点配置文件：
+
+```bash
+# 复制到 Nginx 配置目录
+cp docs/nginx.conf /etc/nginx/sites-available/ai-chat
+ln -s /etc/nginx/sites-available/ai-chat /etc/nginx/sites-enabled/
+
+# 编辑配置，修改 server_name 和 root 路径
+vim /etc/nginx/sites-available/ai-chat
+
+# 测试并重载
+nginx -t && nginx -s reload
+```
+
+### 3. 创建数据库
+
+```sql
+CREATE DATABASE ai_chat DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'ai_chat'@'localhost' IDENTIFIED BY 'your_password';
+GRANT ALL PRIVILEGES ON ai_chat.* TO 'ai_chat'@'localhost';
+FLUSH PRIVILEGES;
+```
+
+### 4. 目录权限

 ```bash
 chown -R www-data:www-data /path/to/ai-chat
@@ -62,6 +97,22 @@ chmod 755 /path/to/ai-chat/public/uploads
 chmod 755 /path/to/ai-chat/config
 ```

+### 5. 运行安装向导
+
+访问 `http://your-domain.com/install.php`
+
+---
+
+## 本地开发（PHP 内置服务器）
+
+```bash
+php -S localhost:8080 -t public/ public/router.php
+```
+
+> 必须使用 `public/router.php` 作为路由文件，否则 `/api/*` 请求无法正确路由到 `api.php`。
+
+---
+
 ## 安全建议

 1. 配置 SSL 证书（HTTPS）
--- a/docs/baota-nginx-snippet.conf
+++ b/docs/baota-nginx-snippet.conf
@@ -1,35 +1,24 @@
 # ============================================================
-# AI Chat 宝塔面板 Nginx 配置片段（PHP-FPM 版本）
+# AI Chat - 宝塔面板伪静态规则
 # ============================================================
 #
-# 【使用说明】
-# 1. 本文件为宝塔面板专用的 Nginx 配置片段，不是完整的站点配置文件。
-# 2. 使用步骤：
-#    a. 在宝塔面板中创建网站，PHP 版本选择 PHP 8.0
-#    b. 将网站根目录指向 /path/to/ai-chat/public
-#    c. 登录宝塔面板 → 网站 → 找到你的站点 → 点击"设置"
-#    d. 在左侧菜单选择"配置文件"
-#    e. 将下方"配置内容开始"到"配置内容结束"之间的内容，
-#       复制并粘贴到 server { } 块内（注意不要重复嵌套 server 块）
-#    f. 保存即可生效
-# 3. 前置准备：
-#    - 在宝塔面板中安装 PHP 8.0 并启用
-#    - 安装 MySQL 5.7+ 或 8.0
-#    - 安装 Composer
-#    - 运行 composer install 安装 PHP 依赖
+# 使用方法：
+#   宝塔面板 → 网站 → 找到你的站点 → 设置 → 伪静态
+#   将本文件内容完整粘贴到伪静态输入框中，保存即可
+#
+# 前置条件：
+#   - 网站根目录已指向 public/ 目录
+#   - PHP 8.0 已在宝塔中安装并启用
+#   - 如 PHP 版本非 8.0，需将下方 php-cgi-80 改为对应版本号
 #
 # ============================================================

-# ↓↓↓ 配置内容开始 ↓↓↓
-
-# === AI Chat 网站配置（PHP-FPM） ===
-
-# 1. 默认路由
+# 默认路由
 location / {
    try_files $uri $uri/ /login.php;
 }

-# 2. API 路由 - 转发到 api.php
+# API 路由 — 将 /api/* 请求转发到 api.php 处理
 location /api/ {
    try_files $uri /api.php$is_args$args;
    fastcgi_pass unix:/tmp/php-cgi-80.sock;
@@ -40,47 +29,39 @@ location /api/ {
    fastcgi_param REQUEST_URI $request_uri;
 }

-# 3. SSE 流式响应特殊配置（AI对话需要）
-#    针对 Chat API 的 SSE（Server-Sent Events）流式响应，
-#    需要禁用所有缓冲以确保实时输出
+# SSE 流式响应 — AI 对话需要禁用缓冲以实现实时输出
 location /api/chat/completions {
    fastcgi_pass unix:/tmp/php-cgi-80.sock;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root/api.php;
    fastcgi_param REQUEST_URI $request_uri;
-    # SSE 关键配置
    fastcgi_buffering off;
+    fastcgi_cache off;
    proxy_buffering off;
    add_header X-Accel-Buffering no;
-    # 超时设置（5分钟）
    fastcgi_read_timeout 300s;
 }

-# 4. 静态资源缓存（assets/ 和 uploads/ 已在 public 目录下，无需 alias）
+# 静态资源缓存
 location /assets/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
 }

-# 5. 上传文件缓存
+# 上传文件缓存
 location /uploads/ {
    expires 7d;
    add_header Cache-Control "public";
 }

-# 6. 禁止访问非公开目录（安全）
-location ~ /(app|config|vendor|tests|scripts|)/ {
+# 禁止访问非公开目录
+location ~ /(app|config|vendor|tests|scripts|\.cospec)/ {
    deny all;
    return 404;
 }

-# 7. 禁止访问隐藏文件
+# 禁止访问隐藏文件
 location ~ /\. {
    deny all;
    return 404;
 }
-
-# 8. 上传文件大小限制
-client_max_body_size 10m;
-
-# ↑↑↑ 配置内容结束 ↑↑↑
--- a/docs/nginx.conf
+++ b/docs/nginx.conf
@@ -1,14 +1,25 @@
-# AI Chat 应用 Nginx 配置（PHP-FPM 版本）
-# 将此文件复制到 /etc/nginx/sites-available/ 并创建软链接到 sites-enabled/
+# ============================================================
+# AI Chat - Nginx 完整站点配置文件
+# ============================================================
 #
-# 注意：本文件为完整的 Nginx 站点配置，适用于直接部署到 Nginx + PHP-FPM 的场景。
-# 如果你使用宝塔面板管理服务器，请参考 baota-nginx-snippet.conf 文件中的配置片段。
+# 适用场景：直接部署到 Nginx + PHP-FPM（不使用宝塔面板）
+#
+# 使用方法：
+#   1. 将本文件复制到 /etc/nginx/sites-available/ai-chat
+#   2. 创建软链接：ln -s /etc/nginx/sites-available/ai-chat /etc/nginx/sites-enabled/
+#   3. 修改下方 server_name 和 root 为实际值
+#   4. 如 PHP 版本非 8.0，需将 php-cgi-80 改为对应版本号
+#   5. nginx -t 测试配置，nginx -s reload 重载生效
+#
+# 注意：
+#   如果你使用宝塔面板，请勿使用本文件，改用 baota-nginx-snippet.conf（伪静态规则）
 #
 # 前置条件：
-# - PHP 8.0+ 已安装并启用 PHP-FPM
-# - MySQL 5.7+ 已安装
-# - Composer 已安装
-# - 项目已部署到 /path/to/ai-chat/ 目录
+#   - PHP 8.0+ 已安装并启用 PHP-FPM
+#   - MySQL 5.7+ 已安装
+#   - Composer 已安装
+#   - 项目已部署到服务器目录
+#

 server {
    listen 80;