初始化

2026-07-03 16:01:08 +08:00
parent dc90e889e1
commit b51ee98afa
37 changed files with 6282 additions and 0 deletions
--- a/docs/STARTUP.md
+++ b/docs/STARTUP.md
@@ -0,0 +1,310 @@
+# 文件管理系统 - 部署启动指南
+
+## 一、环境要求
+
+| 组件 | 版本要求 | 说明 |
+|------|----------|------|
+| Go | 1.21+ | 后端运行环境 |
+| Node.js | 18+ | 前端构建环境 |
+| MySQL | 8.0+ | 数据库 |
+| MinIO | 最新 | 对象存储(可选) |
+| Nginx | 最新 | 反向代理(生产环境) |
+
+---
+
+## 二、数据库初始化
+
+### 1. 创建数据库
+
+```bash
+mysql -u root -p
+```
+
+```sql
+CREATE DATABASE seeyon_fs DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+### 2. 导入表结构
+
+```bash
+mysql -u root -p seeyon_fs < server/sql/init.sql
+```
+
+> 表结构会在首次启动时由 GORM 自动迁移, 手动导入可确保初始数据(管理员账号、默认角色)正确创建。
+
+---
+
+## 三、后端启动
+
+### 1. 进入后端目录
+
+```bash
+cd server
+```
+
+### 2. 修改配置文件
+
+编辑 `config.yaml`:
+
+```yaml
+server:
+  port: 8080
+  mode: debug
+  public_url: "http://localhost:5173"  # 前端访问地址
+
+database:
+  host: 127.0.0.1
+  port: 3306
+  username: root
+  password: "123456"       # 改为你的MySQL密码
+  dbname: seeyon_fs
+
+jwt:
+  secret: "your-secret-key"  # 生产环境务必修改
+  expiration: 24
+
+storage:
+  default_policy_id: 1
+  local_base_path: D:/Seeyon/A8/localfile  # 文件存储根目录
+  cdn_host: "http://localhost:3090"         # Nginx地址
+  cdn_path_prefix: "/public"
+```
+
+### 3. 安装依赖
+
+```bash
+# 设置Go代理(国内网络)
+export GOPROXY=https://goproxy.cn,direct
+
+# 下载依赖
+go mod tidy
+```
+
+### 4. 编译
+
+```bash
+go build -o server.exe main.go
+```
+
+### 5. 启动
+
+```bash
+# 前台运行
+./server.exe
+
+# 后台运行(Linux/Mac)
+nohup ./server.exe > server.log 2>&1 &
+
+# 后台运行(Windows PowerShell)
+Start-Process -FilePath ".\server.exe" -RedirectStandardOutput "server.log" -NoNewWindow
+```
+
+### 6. 验证
+
+```bash
+# 健康检查
+curl http://localhost:8080/health
+# 返回: {"status":"ok"}
+
+# 测试登录
+curl -X POST http://localhost:8080/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+---
+
+## 四、前端启动
+
+### 1. 进入前端目录
+
+```bash
+cd web
+```
+
+### 2. 安装依赖
+
+```bash
+npm install
+```
+
+### 3. 开发模式启动
+
+```bash
+npm run dev
+```
+
+前端运行在 `http://localhost:5173`, API 请求自动代理到后端 `http://localhost:8080`。
+
+### 4. 生产构建
+
+```bash
+npm run build
+```
+
+构建产物在 `web/dist/` 目录, 由 Nginx 提供静态文件服务。
+
+---
+
+## 五、Nginx 配置(生产环境)
+
+### 1. 安装 Nginx
+
+Windows 下载: http://nginx.org/en/download.html
+
+### 2. 配置
+
+将 `server/docs/nginx-production.conf` 复制到 Nginx 配置目录, 修改以下内容:
+
+```nginx
+server {
+    listen 80;
+    server_name 你的域名;  # 改为实际域名或IP
+
+    # 前端静态资源
+    location / {
+        root D:/Seeyon/A8/frontend/dist;  # 前端构建产物路径
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API代理
+    location ^~ /api/ {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # MinIO代理(预签名模式)
+    location ^~ /minio/ {
+        proxy_pass http://127.0.0.1:9000/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 300s;
+        proxy_buffering off;
+    }
+}
+```
+
+### 3. 启动 Nginx
+
+```bash
+# Windows
+nginx.exe
+
+# Linux
+sudo systemctl start nginx
+```
+
+---
+
+## 六、MinIO 配置(可选)
+
+### 1. 启动 MinIO
+
+```bash
+# Windows
+minio.exe server D:\minio\data --console-address :9001 --address :9000
+
+# Linux
+minio server /data --console-address :9001 --address :9000
+```
+
+### 2. 登录 MinIO 控制台
+
+访问 `http://localhost:9001`, 默认账号: `minioadmin / minioadmin`
+
+### 3. 创建 Bucket
+
+创建名为 `seeyon-fs` 的 Bucket。
+
+### 4. 在系统中配置 MinIO 存储策略
+
+登录文件管理系统后台 → 存储策略 → 新建:
+
+```json
+{
+  "name": "MinIO存储",
+  "type": "minio",
+  "config": {
+    "endpoint": "localhost:9000",
+    "access_key": "你的AccessKey",
+    "secret_key": "你的SecretKey",
+    "bucket": "seeyon-fs",
+    "use_ssl": false,
+    "access_mode": "presigned",
+    "nginx_endpoint": "http://你的域名/minio"
+  }
+}
+```
+
+---
+
+## 七、默认账号
+
+| 账号 | 密码 | 角色 |
+|------|------|------|
+| admin | admin123 | 管理员 |
+
+> 首次登录后请立即修改密码。
+
+---
+
+## 八、目录结构
+
+```
+SeeyonFileSystem/
+├── server/                  # Go后端
+│   ├── main.go              # 入口
+│   ├── config.yaml          # 配置文件
+│   ├── config/              # 配置加载
+│   ├── api/                 # 路由定义
+│   ├── controller/          # 控制器
+│   ├── service/             # 业务逻辑
+│   ├── repository/          # 数据访问
+│   ├── model/               # 数据模型
+│   ├── middleware/           # 中间件
+│   ├── storage/             # 存储引擎
+│   ├── dto/                 # 数据传输对象
+│   ├── utils/               # 工具函数
+│   ├── sql/                 # SQL脚本
+│   └── docs/                # 文档
+│
+├── web/                     # Vue3前端
+│   ├── src/
+│   │   ├── views/           # 页面
+│   │   ├── components/      # 组件
+│   │   ├── api/             # API封装
+│   │   ├── stores/          # 状态管理
+│   │   └── router/          # 路由
+│   └── dist/                # 构建产物
+│
+└── data/storage/            # 本地文件存储
+```
+
+---
+
+## 九、常见问题
+
+### Q: 启动报错 "连接数据库失败"
+
+检查 `config.yaml` 中的数据库配置是否正确, 确认 MySQL 服务已启动。
+
+### Q: 前端页面空白
+
+检查 Nginx 配置中 `root` 路径是否指向正确的 `dist` 目录, 确保 `try_files` 配置正确。
+
+### Q: 文件上传失败
+
+检查 `storage.local_base_path` 目录是否存在且有写入权限。
+
+### Q: MinIO 连接失败
+
+检查 MinIO 服务是否启动, `endpoint` 配置是否正确, `access_key` 和 `secret_key` 是否匹配。
+
+### Q: 分享链接无法访问
+
+检查 `server.public_url` 配置是否为前端的实际访问地址。
+
+### Q: 中文文件名乱码
+
+确保 MySQL 使用 `utf8mb4` 字符集, 客户端发送请求时使用 UTF-8 编码。