leaudit-platform-frontend/docs/docker-deployment.md

# Docker 部署指南

## 环境变量工作原理

### 在 Remix 项目中如何工作

1. **构建时环境变量**: 在 Docker 构建时，环境变量会被嵌入到构建产物中
2. **运行时环境变量**: 通过 `dotenv` 包在应用启动时加载环境变量
3. **客户端环境变量**: 以 `NEXT_PUBLIC_` 开头的变量可以在客户端访问

### API 配置文件的识别机制

我们的 `app/config/api-config.ts` 配置文件通过以下方式识别环境变量：

```typescript
// 从环境变量获取配置，如果环境变量不存在则使用默认配置
const getConfigFromEnv = (defaultConfig: ApiConfig): ApiConfig => {
  return {
    baseUrl: process.env.NEXT_PUBLIC_API_BASE_URL || defaultConfig.baseUrl,
    documentUrl: process.env.NEXT_PUBLIC_DOCUMENT_URL || defaultConfig.documentUrl,
    uploadUrl: process.env.NEXT_PUBLIC_UPLOAD_URL || defaultConfig.uploadUrl,
    postgrestUrl: process.env.NEXT_PUBLIC_POSTGREST_URL || defaultConfig.postgrestUrl,
  };
};
```

### 文件使用配置的映射关系

1. **app/api/axios-client.ts** 使用：
   - `API_BASE_URL` (来自 `NEXT_PUBLIC_API_BASE_URL`)
   - `DOCUMENT_URL` (来自 `NEXT_PUBLIC_DOCUMENT_URL`)

2. **app/api/files/files-upload.ts** 使用：
   - `UPLOAD_URL` (来自 `NEXT_PUBLIC_UPLOAD_URL`)

## Docker 部署方式

### 方式一：直接使用 docker run 命令

```bash
# 构建镜像
docker build -t docreview-app .

# 运行容器，通过 -e 参数传入环境变量
docker run -d \
  --name docreview \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e NEXT_PUBLIC_API_BASE_URL=http://your-api-server.com:3000 \
  -e NEXT_PUBLIC_DOCUMENT_URL=http://your-docs-server.com:9000/docauditai/ \
  -e NEXT_PUBLIC_UPLOAD_URL=http://your-upload-server.com:8008/admin/documents/upload \
  docreview-app
```

### 方式二：使用 docker-compose

1. **使用内联环境变量**:

```yaml
# docker-compose.yml
version: '3.8'
services:
  docreview-app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_BASE_URL=http://api.company.com:3000
      - NEXT_PUBLIC_DOCUMENT_URL=http://docs.company.com:9000/docauditai/
      - NEXT_PUBLIC_UPLOAD_URL=http://upload.company.com:8008/admin/documents/upload
```

2. **使用环境变量文件**:

创建 `.env.production` 文件：
```bash
NODE_ENV=production
NEXT_PUBLIC_API_BASE_URL=http://api.company.com:3000
NEXT_PUBLIC_DOCUMENT_URL=http://docs.company.com:9000/docauditai/
NEXT_PUBLIC_UPLOAD_URL=http://upload.company.com:8008/admin/documents/upload
```

然后在 docker-compose.yml 中引用：
```yaml
services:
  docreview-app:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env.production
```

### 方式三：Kubernetes 部署

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docreview-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: docreview-app
  template:
    metadata:
      labels:
        app: docreview-app
    spec:
      containers:
      - name: docreview-app
        image: docreview-app:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
        - name: NEXT_PUBLIC_API_BASE_URL
          value: "http://api.company.com:3000"
        - name: NEXT_PUBLIC_DOCUMENT_URL
          value: "http://docs.company.com:9000/docauditai/"
        - name: NEXT_PUBLIC_UPLOAD_URL
          value: "http://upload.company.com:8008/admin/documents/upload"
```

## 环境变量验证

### 在容器内检查环境变量

```bash
# 进入运行中的容器
docker exec -it docreview /bin/sh

# 查看环境变量
env | grep NEXT_PUBLIC

# 或者查看具体变量
echo $NEXT_PUBLIC_API_BASE_URL
echo $NEXT_PUBLIC_DOCUMENT_URL
echo $NEXT_PUBLIC_UPLOAD_URL
```

### 应用内验证

在开发模式下，配置文件会输出当前使用的配置：
```
📦 API配置信息: {
  environment: "production",
  config: {
    baseUrl: "http://api.company.com:3000",
    documentUrl: "http://docs.company.com:9000/docauditai/",
    uploadUrl: "http://upload.company.com:8008/admin/documents/upload"
  }
}
```

## 构建时的环境变量注入

### 方式一：Docker 构建时传入

```bash
docker build \
  --build-arg NEXT_PUBLIC_API_BASE_URL=http://api.company.com:3000 \
  --build-arg NEXT_PUBLIC_DOCUMENT_URL=http://docs.company.com:9000/docauditai/ \
  --build-arg NEXT_PUBLIC_UPLOAD_URL=http://upload.company.com:8008/admin/documents/upload \
  -t docreview-app .
```

然后在 Dockerfile 中添加：
```dockerfile
# 在构建阶段添加
ARG NEXT_PUBLIC_API_BASE_URL
ARG NEXT_PUBLIC_DOCUMENT_URL
ARG NEXT_PUBLIC_UPLOAD_URL

ENV NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL
ENV NEXT_PUBLIC_DOCUMENT_URL=$NEXT_PUBLIC_DOCUMENT_URL
ENV NEXT_PUBLIC_UPLOAD_URL=$NEXT_PUBLIC_UPLOAD_URL
```

## 多环境配置示例

### 开发环境
```bash
# .env.development
NODE_ENV=development
NEXT_PUBLIC_API_BASE_URL=http://localhost:8008
NEXT_PUBLIC_DOCUMENT_URL=http://localhost:9000/docauditai/
NEXT_PUBLIC_UPLOAD_URL=http://localhost:8008/admin/documents/upload
```

### 测试环境
```bash
# .env.testing
NODE_ENV=testing
NEXT_PUBLIC_API_BASE_URL=http://test-api.company.com:3000
NEXT_PUBLIC_DOCUMENT_URL=http://test-docs.company.com:9000/docauditai/
NEXT_PUBLIC_UPLOAD_URL=http://test-upload.company.com:8008/admin/documents/upload
```

### 生产环境
```bash
# .env.production
NODE_ENV=production
NEXT_PUBLIC_API_BASE_URL=http://api.company.com:3000
NEXT_PUBLIC_DOCUMENT_URL=http://docs.company.com:9000/docauditai/
NEXT_PUBLIC_UPLOAD_URL=http://upload.company.com:8008/admin/documents/upload
```

## 部署脚本示例

创建 `deploy.sh` 脚本：

```bash
#!/bin/bash

# 部署脚本
ENV=${1:-production}

echo "部署环境: $ENV"

# 构建镜像
docker build -t docreview-app:$ENV .

# 停止旧容器
docker stop docreview-$ENV 2>/dev/null || true
docker rm docreview-$ENV 2>/dev/null || true

# 根据环境启动容器
case $ENV in
  "development")
    docker run -d \
      --name docreview-$ENV \
      -p 3001:3000 \
      --env-file .env.development \
      docreview-app:$ENV
    ;;
  "testing")
    docker run -d \
      --name docreview-$ENV \
      -p 3002:3000 \
      --env-file .env.testing \
      docreview-app:$ENV
    ;;
  "production")
    docker run -d \
      --name docreview-$ENV \
      -p 3000:3000 \
      --env-file .env.production \
      docreview-app:$ENV
    ;;
esac

echo "部署完成，容器名: docreview-$ENV"
```

使用方法：
```bash
chmod +x deploy.sh
./deploy.sh production  # 部署生产环境
./deploy.sh testing     # 部署测试环境
```

## 注意事项

1. **环境变量优先级**：Docker 环境变量 > 环境变量文件 > 默认配置
2. **客户端变量**：必须以 `NEXT_PUBLIC_` 开头才能在客户端使用
3. **构建时注入**：客户端环境变量在构建时被注入，运行时修改不会生效
4. **安全性**：不要在环境变量中存储敏感信息，如API密钥等
5. **网络访问**：确保容器能够访问配置的API地址