安装部署

海域智舱单机部署拓扑图

本章节基于真实交付的源码（02 素材与源码/）撰写，整体形态如上图：Go + SQLite 零外部依赖，无需 Redis / Postgres / Docker，单二进制 + 单文件即可上线。

一句话部署

bash

git clone https://github.com/deijing/haiyu-zhicang.git
cd haiyu-zhicang
npm install && cd frontend && npm install && cd ../backend && go mod download && cd ..
npm run dev
# 浏览器访问 http://localhost:3000/login

一、源码包目录结构

「02 素材与源码」目录下含 5 个子目录与 1 个完整压缩包：

text

02 素材与源码/
├── 01 sql文件夹/                 # 数据库 SQL（仅参考，启动时自动执行）
├── 02 前端文件夹/                # React 19 + Vite 6 前端
├── 03 后端代码夹/                # Go 1.25 后端
├── 04 图片素材文件夹/            # 演示用图片素材
├── 05 海域智舱完整项目源码.zip   # 一键完整包
└── readme.txt

推荐使用方式

直接解压 05 海域智舱完整项目源码.zip 到工作目录，已包含所有内容（含 root package.json 与依赖编排脚本），不需要手动拼接前面几个文件夹。

解压后的根目录关键结构：

text

比赛项目/
├── frontend/                    # React 19 + Vite 前端
│   ├── index.tsx                # 入口
│   ├── App.tsx                  # 路由
│   ├── MainApp.tsx              # 主应用
│   ├── vite.config.ts           # Vite + PWA 配置
│   ├── package.json
│   └── components/ services/ public/ ...
├── backend/                     # Go HTTP API + SQLite
│   ├── main.go                  # 入口
│   ├── config.go                # 环境变量
│   ├── auth.go quotas.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 Functions（仅参考）
├── package.json                 # 根脚本（concurrently 编排）
└── CLAUDE.md

二、环境要求

软件	最低版本	用途
Node.js	≥ 22.x	前端运行 / 构建
npm	随 Node 自带	包管理
Go	≥ 1.25.5	后端编译运行（`go.mod` 声明）
浏览器	Chrome 110+ / Edge 110+ / Safari 16+	PWA + IndexedDB

bash

node --version    # ≥ v22.0.0
npm --version
go version        # ≥ go1.25.5

Go 国内镜像（可选）

bash

export GOPROXY=https://goproxy.cn,direct

三、开发环境

3.1 安装依赖

bash

# 1. 进入项目根目录（解压后的目录）
cd 比赛项目

# 2. 安装根依赖（仅 concurrently，用于并行启动前后端）
npm install

# 3. 安装前端依赖（react / d3 / vite / vite-plugin-pwa 等）
cd frontend && npm install && cd ..

# 4. 下载后端依赖（modernc.org/sqlite 纯 Go 驱动等）
cd backend && go mod download && cd ..

3.2 一键启动（推荐）

bash

npm run dev

等价于 concurrently 同时启动：

npm run dev:backend → cd backend && go run .（监听 :8788）
npm run dev:frontend → cd frontend && npm run dev（Vite 监听 :3000，/api 代理到 :8788）

启动后控制台输出：

text

[backend]  海域智舱后端已启动: http://localhost:8788
[frontend] VITE v6.x ready in 480 ms
[frontend]   ➜ Local: http://localhost:3000/

3.3 单独启动

bash

npm run dev:backend     # 仅后端 :8788
npm run dev:frontend    # 仅前端 :3000

3.4 浏览器访问

模式	URL	备注
开发	http://localhost:3000/login	Vite 已把 `/api` 代理到 `:8788`
生产（见下节）	http://localhost:8788/login	Go 后端单端口托管前端 dist

默认管理员账号

用户名：admin
密码：admin123
入口：/admin/auth/login
首次登录会自动创建该管理员账号；生产部署必须立即修改密码

四、生产部署

方案一：本地一键启动（推荐演示 / 答辩）

bash

# 1. 构建前端到 frontend/dist
npm run build

# 2. 启动 Go 后端，自动托管 frontend/dist
npm run start
# 等价于 cd backend && go run .

# 3. 浏览器访问
open http://localhost:8788/login

单端口托管原理

backend/main.go 启动时会把 FRONTEND_DIST 环境变量（默认 ../frontend/dist）作为静态资源根目录托管，所有非 /api/* 的请求都返回前端 SPA。开发态分双端口避免 HMR 干扰，生产态合并到单端口便于部署。

方案二：编译为单二进制（U 盘 / 离线部署）

bash

# 在 backend/ 目录下编译
cd backend
go build -o haiyu-server .

# 单独打包：二进制 + frontend/dist + migrations
mkdir -p release/haiyu
cp haiyu-server release/haiyu/
cp -r migrations release/haiyu/
cp -r ../frontend/dist release/haiyu/frontend-dist

# 启动
cd release/haiyu
FRONTEND_DIST=./frontend-dist ./haiyu-server

整个 release 目录约 30-50 MB，可直接拷贝到目标机器运行。

方案三：Nginx + systemd 持久化部署

nginx

# /etc/nginx/sites-available/haiyu.conf
server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8788;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

ini

# /etc/systemd/system/haiyu.service
[Unit]
Description=Haiyu Zhicang Backend
After=network.target

[Service]
Type=simple
User=haiyu
WorkingDirectory=/opt/haiyu
ExecStart=/opt/haiyu/haiyu-server
Restart=always
RestartSec=5
Environment=PORT=8788
Environment=DB_PATH=/opt/haiyu/data/app.db
Environment=FRONTEND_DIST=/opt/haiyu/frontend-dist
Environment=IMAGE_API_KEY=sk-xxx
Environment=COPY_API_KEY=sk-xxx
Environment=TEXT_API_KEY=sk-xxx

[Install]
WantedBy=multi-user.target

bash

sudo systemctl daemon-reload
sudo systemctl enable --now haiyu
sudo systemctl status haiyu

方案四：Cloudflare Pages（旧实现，仅参考）

源码包 legacy/ 与 cloudflare/ 目录保留了 Cloudflare Pages Functions 旧版本，用如下脚本部署：

bash

npm run cf:build       # 构建前端
npm run cf:dev         # 本地预览（wrangler pages dev）
npm run cf:deploy      # 部署到 Cloudflare Pages
npm run cf:d1:migrate  # D1 数据库迁移

已不是主推路径

Cloudflare 版本依赖 D1 + KV，配置较重。比赛展示和私有部署强烈推荐使用 Go + SQLite 单机方案。

五、环境变量

后端入口为 backend/config.go，所有配置从环境变量读取，未配置时使用默认值：

变量名	默认值	说明
`PORT`	`8788`	后端监听端口
`DB_PATH`	`data/app.db`	SQLite 数据库路径（相对 `backend/`）
`FRONTEND_DIST`	`../frontend/dist`	前端静态文件目录
`ALLOWED_ORIGIN`	空	跨域白名单（生产建议填域名）

AI 模型相关

变量名	默认值	说明
`IMAGE_API_KEY`	空	图片直连 API Key
`IMAGE_API_BASE_URL`	`https://api.ikuncode.cc`	图片接口基础 URL
`COPY_API_KEY`	空	Listing 文案 API Key
`COPY_API_BASE_URL`	`https://api.ikuncode.cc/v1`	Copy 接口 URL
`COPY_MODEL`	`gemini-3-flash-preview`	Copy 默认模型
`TEXT_API_KEY`	空	提示词生成 API Key
`TEXT_API_BASE_URL`	`https://toapis.com/v1/responses`	Text API URL
`TEXT_MODEL`	`gpt-5.5`	提示词生成模型
`PRODUCT_ANALYSIS_API_KEY`	空	选品分析 API Key
`PRODUCT_ANALYSIS_API_BASE_URL`	空	选品分析基础 URL
`PRODUCT_ANALYSIS_API_PATH`	空	选品分析具体 path
`PRODUCT_ANALYSIS_MODEL`	`gpt-5.5`	选品分析模型
`VIDEO_API_KEY`	空	视频生成 API Key
`VIDEO_API_BASE_URL`	空	视频生成基础 URL
`VIDEO_API_PATH`	空	视频生成具体 path

不配也能跑

开发期可不配任何 API Key，启动后通过 /admin/api 在线添加供应商即可
环境变量只影响启动时的默认值；后台数据库中的 api_providers 配置优先级更高

.env 示例

bash

# 在 backend/ 目录下创建 .env（团队约定，启动时手动 source）
PORT=8788
DB_PATH=data/app.db
ALLOWED_ORIGIN=https://docs.example.com

IMAGE_API_KEY=sk-img-xxx
IMAGE_API_BASE_URL=https://api.ikuncode.cc

COPY_API_KEY=sk-copy-xxx
COPY_MODEL=gemini-3-flash-preview

TEXT_API_KEY=sk-text-xxx
TEXT_MODEL=gpt-5.5

bash

# 启动时载入
cd backend && set -a && source .env && set +a && go run .

六、首次启动验证

bash

# 1. 健康检查（应返回 401，因为未携带 Cookie）
curl -i http://localhost:8788/api/me

# 2. 管理员首次登录（自动创建 admin 账号）
curl -i -X POST http://localhost:8788/api/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 3. 检查数据库文件
ls -lh backend/data/app.db   # 首次启动后会自动生成

数据库初始化做了什么

创建 users / sessions / quotas / usage_logs / api_providers / model_configs / activation_keys / activation_key_redemptions / kg_entities / kg_relations / request_logs ... 等表
写入 13 份 migration（已应用记录在内置迁移表中）
等待第一次 admin/admin123 登录时自动写入管理员行

七、备份与恢复

7.1 备份

bash

# 单文件备份（最简）
cp backend/data/app.db /backup/app-$(date +%Y%m%d).db

# SQLite 在线热备份（推荐）
sqlite3 backend/data/app.db ".backup /backup/app.db"

# 完整备份（数据库 + 上传素材）
tar czf /backup/haiyu-$(date +%Y%m%d).tar.gz backend/data

7.2 恢复

bash

sudo systemctl stop haiyu        # 停止服务
cp /backup/app-20260501.db backend/data/app.db
sudo systemctl start haiyu

# 完整性检查
sqlite3 backend/data/app.db "PRAGMA integrity_check;"

八、性能调优

调优项	建议	实测效果
SQLite WAL	启动后执行 `PRAGMA journal_mode=WAL`	读写并发提升 3-5 倍
Go GOMAXPROCS	默认 = `runtime.NumCPU()`，无需调整	-
Nginx gzip / brotli	静态资源开启压缩	gzip 减少 60-70% 体积
前端长缓存	`frontend/dist/assets/*` 加 `immutable`	二次访问近乎 0ms
PWA Service Worker	已自动注册	Lighthouse PWA 90 分

九、常见问题

端口被占用

bash

# macOS / Linux
lsof -ti:8788 | xargs kill -9
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :8788
taskkill /PID <pid> /F

# 修改端口
PORT=9000 npm run dev:backend

Go 模块下载失败

bash

export GOPROXY=https://goproxy.cn,direct
export GOSUMDB=sum.golang.google.cn
cd backend && go mod download

数据库锁错误（database is locked）

bash

# 启用 WAL 模式
sqlite3 backend/data/app.db "PRAGMA journal_mode=WAL;"

# 极端情况：删除重建（会清空所有数据）
rm backend/data/app.db
npm run dev:backend  # 启动时自动重建

Vite 端口 3000 被占

编辑 frontend/vite.config.ts 的 server.port，或临时设置：

bash

cd frontend && PORT=3001 npm run dev

Go 1.25 不存在或版本太低

项目使用 go 1.25.5（见 backend/go.mod）。可用 g 或 gvm 管理多版本：

bash

# 用 g 切换
g install 1.25.5
g use 1.25.5

PWA 缓存导致页面不更新

bash

# 浏览器 → Application → Service Workers → Unregister
# 或硬刷新：⌘+Shift+R / Ctrl+Shift+R

十、升级版本

bash

git pull
# 重装依赖（前端 lock 变化时）
cd frontend && npm install && cd ..
cd backend && go mod download && cd ..

# 重新构建 + 重启
npm run build
sudo systemctl restart haiyu

数据库迁移自增量

新增 backend/migrations/00XX_*.sql 后重启服务即生效，已应用过的迁移不会重复执行（基于内置迁移记录表）。

下一步

🎨 使用教程 —— 日常使用流程
🛠️ 管理后台 —— 配置供应商与用户
🔌 API 接口 —— 完整接口文档
📊 测试报告 —— 验证部署是否正确

安装部署 ​

一、源码包目录结构 ​

二、环境要求 ​

三、开发环境 ​

3.1 安装依赖 ​

3.2 一键启动（推荐） ​

3.3 单独启动 ​

3.4 浏览器访问 ​

四、生产部署 ​

方案一：本地一键启动（推荐演示 / 答辩） ​

方案二：编译为单二进制（U 盘 / 离线部署） ​

方案三：Nginx + systemd 持久化部署 ​

方案四：Cloudflare Pages（旧实现，仅参考） ​

五、环境变量 ​

AI 模型相关 ​

.env 示例 ​

六、首次启动验证 ​

七、备份与恢复 ​

7.1 备份 ​

7.2 恢复 ​

八、性能调优 ​

九、常见问题 ​

十、升级版本 ​

下一步 ​

安装部署

一、源码包目录结构

二、环境要求

三、开发环境

3.1 安装依赖

3.2 一键启动（推荐）

3.3 单独启动

3.4 浏览器访问

四、生产部署

方案一：本地一键启动（推荐演示 / 答辩）

方案二：编译为单二进制（U 盘 / 离线部署）

方案三：Nginx + systemd 持久化部署

方案四：Cloudflare Pages（旧实现，仅参考）

五、环境变量

AI 模型相关

.env 示例

六、首次启动验证

七、备份与恢复

7.1 备份

7.2 恢复

八、性能调优

九、常见问题

十、升级版本

下一步