Web_BAI_Manage_ApiServer/docs/deployment.md

# 部署文档

## 部署环境

- Ubuntu 20.04 LTS+
- 宝塔面板 7.0+
- Docker
- Node.js 22+

## 部署架构

```
┌───────────────┐
│  宝塔面板      │
└───────────────┘
        │
        ▼
┌───────────────────────┐
│  Nginx (反向代理)      │
└───────────────────────┘
        │
        ├───────────────┐
        ▼               ▼
┌───────────────┐   ┌───────────────┐
│  前端容器      │   │  后端容器      │
└───────────────┘   └───────────────┘
        │               │
        └───────────────┘
                  │
                  ▼
         ┌────────────────┐
         │  Pocketbase DB  │
         └────────────────┘
```

## 准备工作

### 1. 安装宝塔面板

```bash
# 安装宝塔面板
wget -O install.sh http://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh

# 安装完成后，根据提示访问面板地址并设置账号密码
```

### 2. 安装Docker

在宝塔面板中：
1. 打开「软件商店」
2. 搜索「Docker」并安装
3. 等待安装完成

### 3. 安装Node.js

在宝塔面板中：
1. 打开「软件商店」
2. 搜索「Node.js」并安装对应版本
3. 等待安装完成

## 后端部署

后端建议采用 **dist 发布目录部署**，即：

1. 在构建机执行 `npm run build`
2. 生成 `back-end/dist/` 发布产物
3. 服务器仅部署 `dist/`、`package.json`、`package-lock.json` 与 `.env`
4. 服务器执行 `npm install --omit=dev`
5. 服务器执行 `npm start`

### 1. 创建Dockerfile

在 `back-end` 目录创建 `Dockerfile` 文件：

```dockerfile
FROM node:22-alpine AS build

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

FROM node:22-alpine AS production

WORKDIR /app

COPY --from=build /app/package*.json ./
RUN npm install --omit=dev

COPY --from=build /app/dist ./dist

EXPOSE 3000

CMD ["node", "dist/src/index.js"]
```

### 1.1 本地构建与上传发布包

在 `back-end/` 目录执行：

```bash
npm install
npm run lint
npm run test
npm run build
```

构建成功后会生成：

```text
back-end/dist/
  src/
  spec/
  package.json
  package-lock.json
  .env
  eslint.config.js
```

如果你采用服务器源码分离部署，建议上传以下内容到服务器：

- `dist/`
- `package.json`
- `package-lock.json`
- `.env`

然后在服务器执行：

```bash
npm install --omit=dev
npm start
```

### 2. 创建docker-compose.yml

在项目根目录创建 `docker-compose.yml` 文件：

```yaml
version: '3.8'

services:
  backend:
    build:
      context: ./back-end
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - DB_HOST=db
      - DB_PORT=8080
    depends_on:
      - db
    restart: always

  frontend:
    build:
      context: ./front-end
      dockerfile: Dockerfile
    ports:
      - "80:80"
    restart: always

  db:
    image: pocketbase/pocketbase:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/pb_data
    restart: always
```

### 3. 前端Dockerfile

在 `front-end` 目录创建 `Dockerfile` 文件：

```dockerfile
FROM node:22-alpine as build

WORKDIR /app

COPY package*.json ./
RUN npm install --legacy-peer-deps

COPY . .
RUN npm run build

FROM nginx:alpine

COPY --from=build /app/dist /usr/share/nginx/html

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
```

## 一键部署脚本

### 1. 创建部署脚本

在项目根目录创建 `deploy.sh` 文件：

```bash
#!/bin/bash

# 部署脚本
echo "开始部署BAI管理系统..."

# 停止并移除旧容器
echo "停止并移除旧容器..."
docker-compose down

# 构建并启动新容器
echo "构建并启动新容器..."
docker-compose up -d --build

# 查看容器状态
echo "查看容器状态..."
docker ps

echo "部署完成！"
echo "前端访问地址: http://$(hostname -I | awk '{print $1}')"
echo "后端API地址: http://$(hostname -I | awk '{print $1}'):3000"
echo "Pocketbase管理地址: http://$(hostname -I | awk '{print $1}'):8080/_/"
```

### 2. 赋予脚本执行权限

```bash
chmod +x deploy.sh
```

### 3. 执行部署脚本

```bash
./deploy.sh
```

## 宝塔面板配置

### 1. 添加网站

1. 打开宝塔面板
2. 点击「网站」→「添加站点」
3. 填写域名信息（如果有域名）
4. 选择「纯静态」网站类型
5. 点击「提交」

### 2. 配置反向代理

1. 进入网站设置
2. 点击「反向代理」→「添加反向代理」
3. 配置前端代理：
   - 代理名称：frontend
   - 目标URL：http://localhost:80
  - 发送域名：`bai-api.blv-oa.com`（如前后端分域，请按实际前端域名填写）
4. 配置后端代理：
   - 代理名称：backend
   - 目标URL：http://localhost:3000
  - 发送域名：`bai-api.blv-oa.com`
   - 路径：/api
5. 点击「保存」

### 3. 配置SSL证书（必须）

1. 进入网站设置
2. 点击「SSL」→「Let's Encrypt」
3. 申请并安装SSL证书
4. 开启「强制HTTPS」
5. 确保域名 `bai-api.blv-oa.com` 已正确解析到服务器公网 IP

## 环境变量配置

### 后端环境变量

在 `back-end/.env` 文件中配置：

```env
# Server Configuration
PORT=3000
NODE_ENV=production
APP_PROTOCOL=https
APP_DOMAIN=bai-api.blv-oa.com
APP_BASE_URL=https://bai-api.blv-oa.com

# Database Configuration
DB_HOST=db
DB_PORT=8080
DB_NAME=bai_management

# JWT Configuration
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=24h

# CORS Configuration
CORS_ORIGIN=https://bai-api.blv-oa.com
```

### 前端环境变量

在 `front-end/.env.production` 文件中配置：

```env
VUE_APP_BASE_URL=https://bai-api.blv-oa.com/api
VUE_APP_TITLE=BAI管理系统
VUE_APP_VERSION=1.0.0
```

## 域名解析与 HTTPS 部署建议

正式环境建议按以下方式部署：

1. 将域名 `bai-api.blv-oa.com` 的 DNS A 记录指向服务器公网 IP
2. 宝塔/Nginx 为该域名签发并启用 SSL 证书
3. Nginx 对外暴露 `443`，再反向代理到容器内 `backend:3000`
4. 前端生产环境接口地址统一使用：`https://bai-api.blv-oa.com/api`
5. 后端对外公开地址统一使用 `APP_BASE_URL=https://bai-api.blv-oa.com`

### 大文件上传反向代理配置

如果 PocketBase 管理页或 hooks 页面需要上传较大的图片/视频附件，Nginx 需要同步放开请求体大小限制，否则浏览器会直接收到 `413 Content Too Large`，前端通常会看到 HTML 错页而不是 JSON。

建议在站点或对应 `location` 中增加：

```nginx
client_max_body_size 200m;
proxy_request_buffering off;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
```

如果当前 `tbl_attachments.attachments_link` 已放宽到约 4GB，反向代理层仍然需要按你的目标上传体积同步放开，否则即使 PocketBase 集合字段允许更大文件，上传仍会在进入 PocketBase 之前被拦截。

## 数据库配置

### Pocketbase设置

1. 访问 Pocketbase 管理界面：http://服务器IP:8080/_/
2. 创建管理员账号
3. 创建必要的集合：
   - users (用户)
   - data (数据)
   - videos (视频)
   - logs (日志)

## 监控与维护

### 后端发布命令

后端推荐命令：

```bash
# 构建发布产物
npm run build

# 生产启动
npm start
```

### 查看日志

```bash
# 查看后端日志
docker logs -f backend

# 查看前端日志
docker logs -f frontend

# 查看数据库日志
docker logs -f db
```

### 备份数据

```bash
# 备份Pocketbase数据
docker cp db:/pb_data ./backup

# 恢复Pocketbase数据
docker cp ./backup db:/pb_data
```

### 升级项目

1. 拉取最新代码
2. 执行部署脚本：`./deploy.sh`

## 常见问题

### 1. 容器启动失败

检查容器日志：
```bash
docker logs -f 容器名称
```

### 2. 访问接口报错

- 检查反向代理配置
- 检查后端服务是否正常运行
- 检查数据库连接是否正常

### 3. 前端页面空白

- 检查前端容器是否正常运行
- 检查Nginx配置
- 检查API地址配置是否正确

### 4. 数据库连接失败

- 检查数据库容器是否正常运行
- 检查数据库连接配置
- 检查网络连接

## 性能优化

### 1. 前端优化

- 启用Gzip压缩
- 静态资源缓存
- 代码分割
- 图片优化

### 2. 后端优化

- 使用PM2进程管理
- 数据库索引优化
- 缓存策略
- 负载均衡

### 3. 服务器优化

- 调整Docker内存限制
- 配置Nginx缓存
- 启用HTTPS
- 定期清理日志

## 安全措施

### 1. 服务器安全

- 配置防火墙
- 禁用root登录
- 使用SSH密钥认证
- 定期更新系统

### 2. 应用安全

- 使用HTTPS
- 密码加密存储
- 输入验证
- 防止SQL注入
- 防止XSS攻击

### 3. 数据安全

- 定期备份数据
- 数据加密
- 访问控制
- 审计日志

## 总结

本部署方案采用Docker容器化部署，实现了前后端分离的架构，支持一键部署和自动化管理。通过宝塔面板的反向代理功能，实现了域名访问和SSL证书配置，为系统提供了安全、稳定的运行环境。