# 部署指南 (Deployment Guide)

本指南将指导您将应用部署到已安装 iPanel/宝塔面板 和 Node.js 环境的 Linux 服务器上。

## 1. 准备工作

### 启用 Standalone 模式 (已自动配置)
为了减小服务器上的文件体积，我们已经在 `next.config.ts` 中启用了 `output: 'standalone'` 模式。这会创建一个包含所有必要依赖的精简构建包。

### 检查环境
确保您的服务器已安装：
- **Node.js**: 版本需 >= 18.0.0 (推荐 v20 LTS)
- **Nginx**: 用于反向代理
- **PM2**: 用于进程守护 (通常面板可以一键安装，或通过 `npm install -g pm2` 安装)
- **Database**: 您的代码目前使用 SQLite (本地文件)，部署非常简单。

## 2. 构建项目

在**本地电脑**上执行构建命令：

```bash
# 1. 安装依赖 (仅当添加了新包时需要)
npm install

# 2. 生成 Prisma 客户端 (仅当修改了数据库结构时需要)
npx prisma generate

# 3. 构建项目
npm run build
```

构建完成后，您会看到一个 `.next` 文件夹。

## 3. 打包发布 (推荐方式)

我们已经将繁琐的文件复制步骤自动化了。请按照以下“标准流程”进行部署：

### 3.1 本地构建 & 打包

1.  **构建**:
    ```bash
    npm run build
    ```

2.  **打包** (运行自动化脚本):
    在 PowerShell 中执行：
    ```powershell
    ./scripts/build-dockerapp.ps1
    ```
    *这个脚本会自动将 `standalone`, `static`, `public`, `prisma`, `docker-compose.yml` 等所有必要文件整理到项目根目录下的 **`dockerapp`** 文件夹中。*

### 3.2 上传 & 部署

1.  **上传**:
    将整个 **`dockerapp`** 文件夹上传到服务器（例如 `/www/wwwroot/wojide/dockerapp`）。

2.  **启动**:
    进入服务器上的该目录，运行 Docker Compose：
    ```bash
    cd dockerapp
    docker-compose up -d --build
    ```

此方式会自动使用包内的 `Dockerfile` 和 `docker-compose.yml` 构建并启动服务，无需再手动配置 Nginx 或 PM2（Docker 会处理端口映射，通常映射到 3001 或您配置的端口）。

**目录结构说明 (`dockerapp` 文件夹内)**:
```text
dockerapp/
├── .next/            <-- 包含 static 和 standalone/server
├── node_modules/     <-- 最小化依赖
├── public/           <-- 静态资源
├── prisma/           <-- 数据库结构
├── Dockerfile        <-- 构建脚本
├── docker-compose.yml <-- 编排脚本
└── ...
```
## 4. 1Panel 面板配置指南 (图形化界面)

根据您提供的 1Panel 创建运行环境截图，请按以下方式填写：

- **名称**: `wojide` (或任意您喜欢的名字)
- **应用**: `Node.js` (版本保持默认或选择 LTS 版本)
- **项目目录**: 选择您在第 3 步上传文件的目录 (例如 `/www/wwwroot/wojide`)
- **启动命令**: 
    - **开启 [自定义启动命令] 开关** (非常重要!)
    - 输入命令: `node server.js`
    - *解释: Standalone 模式下直接运行 server.js 即可，不需要 npm run start。*
- **包管理器**: `npm`
- **端口**: 如果有端口设置，请输入 `3000`

点击确认创建后，容器会自动启动。

## 5. 服务器端配置 (数据库迁移)

登录服务器终端 (SSH) 或使用面板的终端功能。

### 5.1 数据库迁移
进入网站目录并运行迁移，确保 `dev.db` 存在：

```bash
### 5.1 数据库迁移
进入网站目录并运行迁移，确保 `dev.db` 存在：

**情况 A: 直接安装的 Node 环境 (宝塔默认)**
```bash
cd /www/wwwroot/wojide
npx prisma migrate deploy
```

**情况 B: Docker 部署 (1Panel / 容器化)**

即使文件在宿主机上，Docker 容器也能通过“挂载”访问它们。您只需**进入容器**并找到那个挂载目录。

1.  **确定容器**: 在 1Panel 找到您的应用容器 ID。
2.  **进入容器并运行**:

    ```bash
    # 1. 登录容器
    docker exec -it <container_id> sh

    # 2. 寻找项目目录 (关键步骤!)
    # 在 1Panel 中，网站目录通常也会挂载到容器内的相同路径，或者 /app 目录。
    # 尝试进入：
    cd /www/wwwroot/wojide  
    # 或者 ls /app 看看是否有文件

    # 3. 确认你在正确的目录下 (应该能看到 prisma 文件夹)
    ls 

    # 4. 运行迁移 (更稳妥的方式: 先全局安装指定版本)
    # 先安装 CLI 工具
    npm install -g prisma@5.10.2

    # 然后运行迁移
    prisma migrate deploy

    # 5. 退出
    exit
    ```
```

### 5.2 启动服务

使用 PM2 启动项目：

```bash
# 启动
pm2 start server.js --name "wojide-app"

# 查看状态
pm2 status

# 如果报错，查看日志
pm2 logs wojide-app
```

此时，项目应该运行在 `http://localhost:3000`。

## 6. 初始化配置 (重要!)

首次部署后，数据库是空的，还没有设置密码。
您需要手动调用一次初始化接口来创建默认密码 (`admin`)。

**方法 A: 使用 Curl (在服务器终端)**
```bash
curl -X POST http://localhost:3000/api/settings/init
```
如果成功，会返回 `Initialized default settings`。

**方法 B: 使用浏览器控制台**
如果不方便用 Curl，可以在您的电脑浏览器打开网站登录页，按 `F12` 打开控制台，输入以下代码并回车：
```js
fetch('/api/settings/init', { method: 'POST' }).then(r=>r.json()).then(console.log)
```

初始化成功后，您可以使用默认密码 **`admin`** 登录。

## 7. 配置 Nginx 反向代理 (通过面板)

在面板中找到您的网站设置 -> **反向代理 (Reverse Proxy)**。

- **代理名称**: NextJS
- **目标 URL**: `http://127.0.0.1:3000`
- **发送域名**: `$host`

保存后，您应该可以通过域名访问您的网站了。

## 8. 后续更新 (代码修改后)

当您修改了代码并想要更新服务器版本时：

1.  **本地构建**: 运行 `npm run build`。
2.  **上传覆盖**:
    - 上传 `.next/standalone` 中的内容覆盖服务器对应文件。
    - 上传 `.next/static` 覆盖服务器上的 `.next/static`。
3.  **重启服务**:
    - 在 1Panel 容器列表中，点击该容器的 **“重启”** 按钮。

**注意**: 如果您修改了数据库结构 (`schema.prisma`)，请在重启前参考第 5.1 步进入容器运行 `npx prisma migrate deploy`。

## 常见问题

- **样式丢失?**
  请检查步骤 3/4，确保 `.next/static` 文件夹已正确上传到服务器的 `.next/static` 路径。Standalone 模式默认不包含静态资源，需要手动复制。

- **数据库报错?**
  确保 `.env` 文件中的 `DATABASE_URL` 路径正确。对于 SQLite，建议使用绝对路径，例如 `file:/www/wwwroot/your-website/prisma/dev.db`。

- **权限问题?**
  确保网站目录的所有者是运行 Nginx/Node 的用户 (通常是 `www` 或 `root`，视配置而定)。
