快速开始
5 分钟跑起来
本指南帮你在 5 分钟内完成本地启动并登录平台。
环境要求
| 软件 | 最低版本 | 用途 |
|---|---|---|
| Node.js | ≥ 22.x | 前端运行 / 构建 |
| npm | 随 Node 自带 | 包管理 |
| Go | ≥ 1.25.5 | 后端编译运行（backend/go.mod 声明） |
| 浏览器 | Chrome 110+ / Edge 110+ / Safari 16+ | PWA 与 IndexedDB 支持 |
三步启动
1️⃣ 解压 + 安装依赖
bash
# 解压源码包（来自 02 素材与源码/05 海域智舱完整项目源码.zip）
unzip "海域智舱完整项目源码.zip" -d 比赛项目
cd 比赛项目
# 1. 根依赖（仅 concurrently，用于并行启动前后端）
npm install
# 2. 前端依赖（react / d3 / vite / vite-plugin-pwa 等）
cd frontend && npm install && cd ..
# 3. 后端依赖（modernc.org/sqlite 等）
cd backend && go mod download && cd ..2️⃣ 一键启动
bash
# 同时启动前端 :3000 + 后端 :8788
npm run dev控制台会出现：
text
[backend] 海域智舱后端已启动: http://localhost:8788
[frontend] VITE v6.x ready
[frontend] ➜ Local: http://localhost:3000/3️⃣ 浏览器访问
| 模式 | 访问地址 | 说明 |
|---|---|---|
| 开发模式 | http://localhost:3000/login | Vite 已代理 /api 到 :8788 |
| 生产模式 | http://localhost:8788/login | 需先 npm run build 再 npm run start |
默认管理员账号
首次登录
- 用户名：
admin - 密码：
admin123 - 入口：
/admin/auth/login或/admin - 首次以此账号登录会自动创建管理员行（写入 SQLite
users表） - 会话 Cookie 名为
hyzc_session（HttpOnly + SameSite=Strict） - ⚠️ 生产部署务必立即修改默认密码
登录页预览
普通用户登录
管理员登录
常用命令（来自根 package.json）
bash
# 完整本地开发：Go 后端 8788 + Vite 前端 3000
npm run dev
# 只启动后端（cd backend && go run .）
npm run dev:backend
# 只启动前端（cd frontend && npm run dev）
npm run dev:frontend
# 构建前端到 frontend/dist
npm run build
# 生产启动（Go 单端口托管前端 dist）
npm run start
# 后端 Go 测试
npm run test:backend
# 后端测试 + 前端构建（CI 用）
npm run test
# Cloudflare Pages 部署（旧实现，参考）
npm run cf:dev
npm run cf:deploy项目结构
text
比赛项目/
├── frontend/ # React 19 + Vite 6 前端
│ ├── index.tsx # React 入口
│ ├── App.tsx # 路由（/login, /, /admin, ...）
│ ├── MainApp.tsx # 主应用容器
│ ├── components/ # UI 组件
│ ├── services/ # API 封装 + IndexedDB
│ ├── public/ # 静态资源 + PWA 图标
│ ├── vite.config.ts # Vite + PWA 配置
│ └── package.json
├── backend/ # Go 1.25 + SQLite 后端
│ ├── main.go # 入口（监听 :8788）
│ ├── config.go # 环境变量加载
│ ├── auth.go # 认证 + Session
│ ├── quotas.go # 三类配额 + 两段式协议
│ ├── generate.go # 图 / 文 / 视频 / 选品生成
│ ├── product_graph.go # GraphRAG 图谱构建
│ ├── providers.go # 多供应商路由
│ ├── activation_keys.go # 激活码体系
│ ├── admin.go # 管理后台接口
│ ├── data/app.db # SQLite 数据库（首次启动自动生成）
│ ├── migrations/ # 13 份 SQL 迁移（启动时自动执行）
│ │ ├── 0001_init.sql
│ │ ├── 0002_api_providers.sql
│ │ └── ... 0013_seed_api_configs.sql
│ ├── go.mod / go.sum
│ └── ...
├── legacy/ # 旧 Cloudflare Pages Functions（参考）
├── cloudflare/ # Cloudflare 部署相关
├── package.json # 根脚本（concurrently 编排）
└── CLAUDE.md下一步
- 📖 完整安装部署 —— 包含构建打包、Nginx 部署、HTTPS 等
- 🎨 使用教程 —— 一键全案、内容生成完整流程
- 🛠️ 管理后台 —— 配置供应商、创建用户、生成激活码
- 🧠 GraphRAG 核心 —— 理解技术原理
遇到问题？
端口被占用
bash
# macOS / Linux 查看端口占用
lsof -i :3000
lsof -i :8788
# 修改端口（在根 package.json 或 vite.config.ts 调整）数据库错误
bash
# 删除数据库重建（会清空所有数据）
rm backend/data/app.db
npm run dev:backend # 启动时自动重建Go 模块下载慢
bash
# 设置 Go 国内镜像
export GOPROXY=https://goproxy.cn,direct
cd backend && go mod download