157 lines
4.0 KiB
Markdown
157 lines
4.0 KiB
Markdown
# 安装指南
|
||
|
||
## 环境要求
|
||
|
||
| 组件 | 最低版本 | 说明 |
|
||
|------|----------|------|
|
||
| PHP | 8.0+ | 需启用 PHP-FPM |
|
||
| MySQL | 5.7+ | 或 MariaDB 10.3+ |
|
||
| Nginx | 1.18+ | 或其他支持 PHP-FPM 的 Web 服务器 |
|
||
| Composer | 2.0+ | PHP 依赖管理工具 |
|
||
|
||
### PHP 扩展要求
|
||
|
||
- PDO（含 PDO MySQL 驱动）
|
||
- cURL
|
||
- JSON
|
||
- mbstring
|
||
- OpenSSL
|
||
|
||
## 安装方式
|
||
|
||
### 方式一：宝塔面板安装（推荐）
|
||
|
||
宝塔面板提供图形化界面，最适合快速部署。
|
||
|
||
#### 1. 安装宝塔面板环境
|
||
|
||
在宝塔面板中安装以下组件：
|
||
- Nginx（任意版本）
|
||
- PHP 8.0（注意选择正确版本）
|
||
- MySQL 5.7 或 8.0
|
||
|
||
#### 2. 创建网站
|
||
|
||
1. 登录宝塔面板
|
||
2. 点击"网站" → "添加站点"
|
||
3. 填写域名，PHP 版本选择 **PHP 8.0**
|
||
4. 数据库选择"不创建"（需在安装前手动创建，安装向导不会自动创建数据库）
|
||
|
||
#### 3. 上传代码
|
||
|
||
将项目代码上传到网站目录（例如 `/www/wwwroot/your-domain.com/`），或使用 Git 克隆。
|
||
|
||
#### 4. 安装 PHP 依赖
|
||
|
||
在宝塔终端中执行：
|
||
```bash
|
||
cd /www/wwwroot/your-domain.com
|
||
composer install
|
||
```
|
||
|
||
#### 5. 设置目录权限
|
||
|
||
```bash
|
||
chmod 755 public/uploads/
|
||
chmod 755 config/
|
||
```
|
||
|
||
#### 6. 配置伪静态
|
||
|
||
1. 在宝塔面板中找到你的站点 → 设置 → **网站目录** → 运行目录改为 `/public`
|
||
2. 站点设置 → **伪静态** → 将 `docs/baota-nginx-snippet.conf` 的内容粘贴进去
|
||
3. 保存配置
|
||
|
||
> 注意：如 PHP 版本不是 8.0，需将配置中的 `php-cgi-80` 改为对应版本号。
|
||
|
||
#### 7. 创建数据库
|
||
|
||
安装向导不会自动创建数据库，需要提前手动创建：
|
||
|
||
1. 宝塔面板 → 数据库 → 添加数据库
|
||
2. 记录数据库名、用户名和密码，安装向导中需要填写
|
||
|
||
#### 8. 运行安装向导
|
||
|
||
访问 `http://your-domain.com/install.php`，按照向导步骤：
|
||
1. **环境检查** — 系统自动检查 PHP 版本和扩展
|
||
2. **数据库配置** — 填写 MySQL 连接信息（数据库需提前创建）
|
||
3. **应用配置** — JWT 密钥（可自动生成）
|
||
4. **管理员账户** — 设置管理员用户名和密码
|
||
5. **AI 供应商** — （可选）配置 AI 服务供应商，安装后也可在设置页面添加
|
||
|
||
### 方式二：手动安装
|
||
|
||
#### 1. 安装环境
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt update
|
||
sudo apt install php8.0-fpm php8.0-mysql php8.0-curl php8.0-mbstring php8.0-xml
|
||
sudo apt install mysql-server nginx composer
|
||
```
|
||
|
||
#### 2. 部署代码
|
||
|
||
```bash
|
||
cd /var/www
|
||
git clone <repository-url> ai-chat
|
||
cd ai-chat
|
||
composer install
|
||
```
|
||
|
||
#### 3. 设置权限
|
||
|
||
```bash
|
||
chown -R www-data:www-data /var/www/ai-chat
|
||
chmod 755 public/uploads/ config/
|
||
```
|
||
|
||
#### 4. 配置 Nginx
|
||
|
||
使用 `docs/nginx.conf` 作为完整站点配置：
|
||
```bash
|
||
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 路径
|
||
nginx -t && nginx -s reload
|
||
```
|
||
|
||
#### 5. 创建数据库
|
||
|
||
```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;
|
||
```
|
||
|
||
#### 6. 运行安装向导
|
||
|
||
访问 `http://your-domain.com/install.php` 完成安装。
|
||
|
||
### 方式三：本地开发
|
||
|
||
```bash
|
||
php -S localhost:8080 -t public/ public/router.php
|
||
```
|
||
|
||
> 必须使用 `public/router.php` 作为路由文件，否则 `/api/*` 请求无法正确路由。
|
||
|
||
## 常见问题
|
||
|
||
### Q: 安装页面空白？
|
||
检查 PHP 版本是否 >= 8.0，以及 PHP 扩展是否已安装。
|
||
|
||
### Q: 500 错误？
|
||
检查 Nginx 错误日志：`tail -f /var/log/nginx/error.log`
|
||
|
||
### Q: 数据库连接失败？
|
||
确认 MySQL 服务正在运行，且数据库已提前创建、账号密码正确。
|
||
|
||
### Q: SSE 流式响应不工作？
|
||
确认 Nginx 配置中已禁用缓冲（参考 `docs/baota-nginx-snippet.conf`）。
|
||
|
||
### Q: API 返回非 JSON 响应？
|
||
检查 Web 服务器是否正确配置了 `/api/` 路由转发。本地开发需使用 `public/router.php`。
|