# 迁移部署说明

本文档用于把 Gemini Draw 迁移到 NAS、Linux 服务器或另一台电脑，并使用 Docker Compose 部署。

## 需要准备

- Docker
- Docker Compose v2
- 当前项目源码
- Gemini API Key
- 一串你自己生成的 API 访问密钥 `API_AUTH_TOKEN`

## 必须修改的配置

如果使用 `npm run dev` / `npm run api` 本地运行，在目标机器项目根目录创建 `.env.local`：

```env
GEMINI_API_KEY="你的_Gemini_API_Key"
API_AUTH_TOKEN="一串足够长的随机访问密钥"
API_AUTH_DISABLED="false"
API_PORT="3002"
APP_PASSWORD="123456"
APP_URL="http://目标机器IP:3000"
```

字段说明：

- `GEMINI_API_KEY`：调用 Gemini 模型的密钥。
- `API_AUTH_TOKEN`：调用本项目 API 的访问密钥，别人调用接口时必须带上。
- `API_AUTH_DISABLED`：必须保持 `false`，只有本机临时调试才可以设为 `true`。
- `API_PORT`：容器内 API 端口，默认 `3002`。
- `APP_PASSWORD`：网页登录密码，默认用户名是 `admin`。
- `APP_URL`：前端访问地址，迁移到 NAS 时建议写成 `http://NAS_IP:3000`。

如果使用 Docker Compose，尤其是在 Container Station 里粘贴 YAML 创建应用，请直接修改 `docker_compose.yaml` 或 `docker_compose_Nas.yaml` 里的 `environment` 字段。Container Station 会从 `/tmp` 校验 YAML，相对环境文件路径容易被解析到 `/tmp` 并失败，所以当前 compose 文件把必要变量直接写在 `environment` 中。

生成随机 `API_AUTH_TOKEN` 的示例：

```bash
openssl rand -hex 32
```

Windows PowerShell：

```powershell
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Minimum 0 -Maximum 256) })
```

## Docker Compose 部署

在项目根目录执行：

```bash
docker compose -f docker_compose.yaml up -d --build
```

查看日志：

```bash
docker logs -f gemini-draw
```

停止服务：

```bash
docker compose -f docker_compose.yaml down
```

重新部署：

```bash
git pull
docker compose -f docker_compose.yaml up -d --build --force-recreate
```

## 访问地址

默认端口：

- 前端页面：`http://目标机器IP:3000`
- API 健康检查：`http://目标机器IP:3002/api/health`

如果要修改宿主机端口，编辑 `docker_compose.yaml`：

```yaml
ports:
  - "4001:3000"
  - "4000:3002"
```

修改后访问地址变为：

- 前端页面：`http://目标机器IP:4001`
- API：`http://目标机器IP:4000`

如果修改了前端宿主机端口，也建议同步修改 `.env.local`：

```env
APP_URL="http://目标机器IP:4001"
```

## API 调用必须带访问密钥

受保护 API 必须带 `API_AUTH_TOKEN`：

```bash
curl http://目标机器IP:3002/api/config \
  -H "Authorization: Bearer 你的_API_AUTH_TOKEN"
```

也可以使用：

```bash
curl http://目标机器IP:3002/api/config \
  -H "x-api-key: 你的_API_AUTH_TOKEN"
```

图片修改示例：

```bash
curl -X POST http://目标机器IP:3002/api/edit-image \
  -H "Authorization: Bearer 你的_API_AUTH_TOKEN" \
  -F "prompt=保留主体不变，把背景改成白色摄影棚风格" \
  -F "imageSize=1K" \
  -F "aspectRatio=1:1" \
  -F "files=@input.png"
```

## 迁移到另一台机器的方案

### 方案 A：通过 Git 迁移

1. 在目标机器安装 Docker 和 Docker Compose。
2. 拉取仓库：

```bash
git clone http://192.168.31.5:5002/admin/Gemini_Draw.git
cd Gemini_Draw
```

3. 创建 `.env.local`，填入目标机器自己的密钥和地址。
4. 启动：

```bash
docker compose -f docker_compose.yaml up -d --build
```

### 方案 B：直接复制目录

1. 复制项目目录到目标机器。
2. 不需要复制这些目录或文件：

```txt
node_modules
dist
.git
.env.local
*.log
```

3. 在目标机器重新创建 `.env.local`。
4. 执行 Docker Compose 启动命令。

## NAS 部署建议

如果部署到 NAS，例如路径 `/share/Container/gemini-drawpicture`：

```bash
cd /share/Container/gemini-drawpicture
docker compose -f docker_compose_Nas.yaml up -d --build
```

`docker_compose_Nas.yaml` 的 `environment` 示例：

```yaml
environment:
  GEMINI_API_KEY: "你的_Gemini_API_Key"
  API_AUTH_TOKEN: "你的_API_访问密钥"
  API_AUTH_DISABLED: "false"
  API_PORT: "3002"
  APP_PASSWORD: "你的网页登录密码"
  APP_URL: "http://192.168.31.5:4001"
```

如果 NAS 上 `3000` 或 `3002` 已被占用，就只改 `docker_compose.yaml` 左侧宿主机端口：

```yaml
ports:
  - "4001:3000"
  - "4000:3002"
```

容器内端口右侧保持不变。

## 常见问题

### 前端能打开，API 不能用

检查容器日志：

```bash
docker logs -f gemini-draw
```

检查健康接口：

```bash
curl http://目标机器IP:3002/api/health
```

### API 返回 Unauthorized

请求缺少 `API_AUTH_TOKEN`。补上：

```txt
Authorization: Bearer 你的_API_AUTH_TOKEN
```

### API 返回 Gemini API key is required

说明没有配置 Gemini Key。检查 `.env.local`：

```env
GEMINI_API_KEY="你的_Gemini_API_Key"
```

也可以单次请求传入：

```txt
x-gemini-api-key: 你的_Gemini_API_Key
```

### 修改环境变量后没有生效

重启容器：

```bash
docker compose -f docker_compose.yaml up -d --force-recreate
```