# 中尚鹏管理系统 - 部署说明

```
作者: rovina
最近修订: 2026/3/2
```

---

## 一、环境要求

| 组件 | 版本 |
|------|------|
| Node.js | 18+ |
| pnpm | 8+ |
| Go | 1.21+ |
| MySQL | 8.0+ |

---

## 二、后端部署

### 2.1 配置文件

复制并修改 `backend/configs/config.dev.yaml`：

```yaml
server:
  port: 8080
  mode: "release"   # 生产环境建议 release
  read_timeout: 30
  write_timeout: 30

database:
  host: "127.0.0.1"   # 或 MySQL 服务地址
  port: 3306
  user: "root"
  password: "your_password"
  dbname: "myapp"
  max_open_conns: 100
  max_idle_conns: 10
  reset_database: false   # 生产务必 false

jwt:
  secret: "your_jwt_secret"
  expire_hours: 24
```

### 2.2 启动

```bash
cd backend

# 指定配置文件（可选，默认 ./configs/config.dev.yaml）
export CONFIG_PATH=./configs/config.prod.yaml

go run ./cmd/api
# 或编译后运行
go build -o zsp-api ./cmd/api && ./zsp-api
```

### 2.3 数据目录

- 单合同附件：`./data/contract/uploads/`
- 批量归档：`./data/contract/batch_archive/`

首次运行会自动创建，需确保进程有写权限。

---

## 三、前端部署

### 3.1 开发环境

```bash
cd frontend
pnpm install
pnpm dev
```

前端默认端口 8848（可改 `.env.development` 中 VITE_PORT），API 请求 `/api/*` 会代理到 `http://127.0.0.1:8080`。

### 3.2 生产构建

```bash
cd frontend
pnpm install
pnpm build
```

产物在 `dist/`，需配合 Nginx 等 Web 服务器部署。

### 3.3 为什么打包部署后访问不到 8080 的数据？

打包后前端是**静态资源**，在**用户浏览器**里运行。请求会发到「打开页面时的那台服务器的同源地址」：

- 开发时：页面来自 `http://127.0.0.1:5173`，Vite 把 `/api` 代理到本机 8080，所以能访问。
- 部署后：页面来自 `http://你的服务器:80`，浏览器只会把 `/api` 发到 `http://你的服务器:80/api`，**不会**自动发到 8080。

因此必须让**提供前端页面的 Web 服务器**（如 Nginx）把 `/api` 反向代理到本机 8080（或后端容器）。同时前端已统一用**相对路径** `/api/xxx`，不再写死 `127.0.0.1:8080`，这样部署后即可通过同源访问到后端。

### 3.4 Nginx 配置

完整配置文件见 `docs/deploy/nginx.conf`，包含：

- SPA 路由重写（`try_files $uri /index.html`）
- API 反向代理（`/api` → `127.0.0.1:8080`）
- 大文件上传支持（`client_max_body_size 100m`）
- 静态文件缓存（合同附件 7 天缓存）
- Gzip 压缩

---

## 四、Docker 部署（可选）

### 4.1 后端 Dockerfile 示例

```dockerfile
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o zsp-api ./cmd/api

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/zsp-api .
COPY --from=builder /app/configs ./configs
RUN mkdir -p data/contract/uploads data/contract/batch_archive
EXPOSE 8080
CMD ["./zsp-api"]
```

### 4.2 运行

```bash
# 需挂载配置与数据目录
docker run -d -p 8080:8080 \
  -v $(pwd)/configs:/app/configs \
  -v $(pwd)/data:/app/data \
  -e CONFIG_PATH=/app/configs/config.prod.yaml \
  zsp-backend
```

---

## 五、健康检查

- 后端：`GET http://{host}:8080/health` 返回 `{"status":"ok"}`
- 合同 API：`GET http://{host}:8080/api/contract` 需返回 JSON

---

## 六、常见问题

1. **跨域**：后端已启用 CORS，生产环境若前后端同域可无需额外配置。
2. **文件访问**：合同文件通过 `/api/contract-files/{path}` 访问，确保 Nginx 将 `/api` 转发至后端。
3. **数据库**：首次部署需确保 MySQL 已创建 `myapp` 库，表由 GORM AutoMigrate 自动创建。
4. **JWT 认证**：除 `/api/auth/login`、`/api/auth/register` 外，所有 API 均需 JWT 认证。前端需在登录后存储 token，并在后续请求中通过 `Authorization: Bearer <token>` 头传递。token 有效期为 24 小时。