first commit

docs/deploy/部署说明.md

@@ -0,0 +1,160 @@
+# 中尚鹏管理系统 - 部署说明
+
+```
+作者: 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 小时。