【水浒传：第四篇】AI江湖 —项目本地化部署指南
·
本项目z站内源代码资源下载地址
水浒传：AI江湖 — 项目部署指南
目标环境: Linux (amd64/arm64)
1. 环境要求
1.1 硬件最低要求
| 资源 | 最低配置 | 推荐配置 |
|---|---|---|
| CPU | 2 核 | 4 核+ |
| 内存 | 1 GB | 2 GB+ |
| 磁盘 | 500 MB | 2 GB+（含数据库增长） |
| 网络 | 公网/内网访问 | 带宽 ≥ 1 Mbps |
1.2 软件依赖
| 软件 | 版本要求 | 用途 | 安装方式 |
|---|---|---|---|
| Bun | ≥ 1.3.0 | JavaScript 运行时 & 包管理器 | curl -fsSL https://bun.sh/install | bash |
| Caddy | ≥ 2.x | 反向代理 & SSL | 见下方安装说明 |
| SQLite | ≥ 3.35 | 嵌入式数据库 | 通常系统自带 |
| git | ≥ 2.x | 代码拉取（可选） | 系统包管理器 |
1.3 安装 Caddy
# Debian/Ubuntu
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy
# 验证安装
caddy version
2. 部署架构总览
2.1 整体部署拓扑
开始前需配置模型，不然会报通信异常，见下图所示：
2.2 请求处理流程
3. 快速开始（本地开发）
3.1 一键启动（推荐）
# 克隆项目
git clone <your-repo-url> my-project
cd my-project
# 使用内置开发脚本启动
bash .zscripts/dev.sh
该脚本会自动完成：
bun install— 安装依赖bun run db:push— 初始化数据库bun run dev— 启动 Next.js 开发服务器（端口 3000）- 健康检查
curl localhost:3000 - 启动 mini-services（如果存在）
3.2 手动启动
cd my-project
# 1. 安装依赖
bun install
# 2. 配置环境变量
cp .env.example .env # 如不存在则手动创建
# 编辑 .env: DATABASE_URL=file:./db/custom.db
# 3. 初始化数据库
bun run db:push
# 4. 启动开发服务器
bun run dev
# 访问 http://localhost:3000
3.3 开发环境目录结构
my-project/
├── src/ # 源代码
├── prisma/
│ └── schema.prisma # 数据模型
├── db/
│ └── custom.db # SQLite 数据库（开发环境）
├── .env # 环境变量（本地）
├── .zscripts/
│ ├── dev.sh # 开发启动脚本
│ ├── build.sh # 生产构建脚本
│ └── start.sh # 生产启动脚本
├── package.json
└── Caddyfile # Caddy 配置
4. 生产部署流程
4.1 部署全流程
4.2 构建产物打包部署
项目内置构建脚本，可将所有产物打包为单个 tar.gz 文件，便于分发：
# 在开发机上执行构建
cd my-project
BUILD_ID=prod-v1.0 bash .zscripts/build.sh
构建脚本会生成 /tmp/build_fullstack_prod-v1.0.tar.gz，包含：
| 内容 | 路径（包内） | 说明 |
|---|---|---|
| Next.js standalone | next-service-dist/ |
独立运行包 |
| 静态资源 | next-service-dist/.next/static/ |
CSS/JS/字体 |
| Public 目录 | next-service-dist/public/ |
静态文件 |
| 数据库 | db/custom.db |
预置种子数据 |
| Mini-services | mini-services-dist/ |
微服务构建产物 |
| Caddy 配置 | Caddyfile |
反向代理配置 |
| 启动脚本 | start.sh |
一键启动脚本 |
4.3 目标服务器部署
# 1. 上传打包文件到目标服务器
scp /tmp/build_fullstack_prod-v1.0.tar.gz user@target-server:/app/
# 2. 在目标服务器上解压
ssh user@target-server
cd /app
mkdir -p shuihu-release
tar -xzf build_fullstack_prod-v1.0.tar.gz -C shuihu-release
cd shuihu-release
# 3. 一键启动
bash start.sh
4.4 手动生产部署（不使用打包脚本）
cd my-project
# 1. 安装依赖
bun install
# 2. 生成 Prisma Client
bun run db:generate
# 3. 初始化/迁移数据库
bun run db:push
# 4. 构建生产版本
bun run build
# 5. 设置环境变量
export NODE_ENV=production
export PORT=3000
export HOSTNAME=0.0.0.0
export DATABASE_URL=file:./db/custom.db
# 6. 后台启动
nohup bun .next/standalone/server.js > server.log 2>&1 &
# 7. 启动 Caddy（前台运行）
caddy run --config Caddyfile --adapter caddyfile
5. 构建产物说明
5.1 Next.js Standalone 模式
项目使用 Next.js 的 output: 'standalone' 模式构建，特点：
- 自包含：包含所有运行时依赖（node_modules 最小化）
- 无 Node.js 要求：通过 Bun 运行时启动
- 体积优化：只打包必要的文件
5.2 构建产物结构
.next/standalone/
├── server.js # 入口文件
├── .next/
│ ├── static/ # 静态资源（CSS/JS/字体）
│ └── ...
├── node_modules/ # 最小化依赖
├── package.json
└── public/ # 静态文件目录
5.3 构建命令详解
# package.json 中的构建脚本
"build": "next build && cp -r .next/static .next/standalone/.next/ && cp -r public .next/standalone/"
| 步骤 | 命令 | 说明 |
|---|---|---|
| 1 | next build |
Next.js 构建（含 standalone 输出） |
| 2 | cp -r .next/static .next/standalone/.next/ |
复制静态资源到 standalone |
| 3 | cp -r public .next/standalone/ |
复制 public 目录 |
6. 配置文件详解
6.1 next.config.ts
// 关键配置项
const nextConfig = {
output: 'standalone', // 独立部署模式
experimental: {
turbopack: true, // 使用 Turbopack 加速构建
},
// ... 其他配置
};
6.2 Caddyfile
:81 {
@transform_port_query {
query XTransformPort=*
}
handle @transform_port_query {
reverse_proxy localhost:{query.XTransformPort} {
header_up Host {host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
header_up X-Real-IP {remote_host}
}
}
handle {
reverse_proxy localhost:3000 {
header_up Host {host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
header_up X-Real-IP {remote_host}
}
}
}
配置说明：
| 配置项 | 说明 |
|---|---|
:81 |
Caddy 监听端口 |
@transform_port_query |
匹配含 ?XTransformPort=xxx 参数请求 |
reverse_proxy localhost:3000 |
默认转发到 Next.js 服务 |
header_up |
转发客户端真实 IP 和协议头 |
6.3 .env 环境变量
# 数据库连接（SQLite 文件路径）
DATABASE_URL=file:./db/custom.db
# AI 模型配置（可选，通过 /api/llm-config 接口设置）
# LLM_API_URL=https://your-llm-api.com/v1
# LLM_API_KEY=sk-xxxxxxxxxxxxxxxx
# LLM_MODEL_ID=gpt-4o
注意：
.env文件中的变量仅在开发环境生效。生产环境通过export命令或 systemd 环境变量设置。
6.4 Prisma Schema
generator client {
provider = "prisma-client-js"
}
datasource db {
provider = "sqlite"
url = env("DATABASE_URL")
}
7. 数据库管理
7.1 数据库架构
7.2 常用数据库操作
# 查看数据库结构
bun run db:push # 同步 schema 到数据库（不丢失数据）
bun run db:generate # 重新生成 Prisma Client
bun run db:migrate # 执行迁移（有迁移文件时）
bun run db:reset # 重置数据库（⚠️ 会删除所有数据）
# 直接操作 SQLite
sqlite3 db/custom.db ".tables" # 查看所有表
sqlite3 db/custom.db ".schema Player" # 查看 Player 表结构
sqlite3 db/custom.db "SELECT COUNT(*) FROM Player;" # 查询玩家数量
7.3 备份与恢复
# 备份
cp db/custom.db "db/backup_$(date +%Y%m%d_%H%M%S).db"
# 恢复
cp db/backup_20260604_120000.db db/custom.db
# 自动备份（crontab）
0 3 * * * cp /app/shuihu-release/db/custom.db /app/backups/db_$(date +\%Y\%m\%d).db
7.4 数据库迁移策略
重要：生产环境首次部署时，构建产物中已包含开发环境的数据库副本作为种子数据。后续更新使用
db:push同步 schema 变更，不会删除已有数据。
8. AI 模型配置
8.1 AI 架构
8.2 配置方式
AI 模型配置通过运行时 API 接口设置，无需重启服务：
# 设置自定义 LLM
curl -X POST http://localhost:3000/api/llm-config \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.openai.com/v1",
"apiKey": "sk-xxxxxxxxxxxxxxxx",
"modelId": "gpt-4o"
}'
# 查看当前配置
curl http://localhost:3000/api/llm-config
8.3 支持的 AI 服务
| 服务商 | API URL 示例 | 模型示例 |
|---|---|---|
| OpenAI | https://api.openai.com/v1 |
gpt-4o, gpt-4o-mini |
| Azure OpenAI | https://xxx.openai.azure.com |
部署名称 |
| 本地模型 | http://localhost:11434/v1 |
llama3, qwen2 |
| 任何 OpenAI 兼容 API | 自定义 URL | 任意 |
8.4 AI 调用参数
| 参数 | 值 | 说明 |
|---|---|---|
max_tokens |
1024 | 单次生成最大 token 数 |
temperature |
0.8 | 创意度（0=确定性，1=高创意） |
timeout |
30s | 请求超时时间 |
9. 反向代理（Caddy）
9.1 端口映射
| 外部端口 | 内部服务 | 说明 |
|---|---|---|
:81 |
localhost:3000 |
默认转发到 Next.js |
:81?XTransformPort=xxxx |
localhost:xxxx |
动态转发到 mini-service |
9.2 添加 HTTPS（生产推荐）
your-domain.com {
reverse_proxy localhost:3000 {
header_up Host {host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
header_up X-Real-IP {remote_host}
}
}
Caddy 会自动从 Let’s Encrypt 获取 SSL 证书，无需额外配置。
9.3 常用 Caddy 命令
# 启动（前台）
caddy run --config Caddyfile --adapter caddyfile
# 后台启动
caddy start --config Caddyfile --adapter caddyfile
# 停止
caddy stop
# 重载配置（不中断服务）
caddy reload --config Caddyfile --adapter caddyfile
# 验证配置
caddy validate --config Caddyfile --adapter caddyfile
10. Mini-Services 管理
10.1 架构说明
10.2 添加新的 Mini-Service
# 1. 创建服务目录
mkdir -p mini-services/my-service
# 2. 创建 package.json
cat > mini-services/my-service/package.json << 'EOF'
{
"name": "my-service",
"scripts": {
"dev": "bun run src/index.ts"
}
}
EOF
# 3. 创建入口文件
cat > mini-services/my-service/src/index.ts << 'EOF'
// 你的服务逻辑
const server = Bun.serve({
port: 4001,
fetch(req) {
return new Response("Hello from my-service!");
},
});
console.log("my-service running on port 4001");
EOF
开发时，dev.sh 会自动扫描 mini-services/ 并启动所有子服务。生产构建时，build.sh 会将其编译为单文件 JS。
11. 环境变量参考
11.1 完整变量列表
| 变量名 | 必需 | 默认值 | 说明 |
|---|---|---|---|
DATABASE_URL |
✅ | file:./db/custom.db |
SQLite 数据库路径 |
NODE_ENV |
— | development |
运行环境 |
PORT |
— | 3000 |
Next.js 服务端口 |
HOSTNAME |
— | 0.0.0.0 |
绑定地址 |
NEXT_TELEMETRY_DISABLED |
— | 1 |
禁用遥测 |
11.2 生产环境设置示例
# 创建环境变量文件
cat > /app/shuihu-release/.env.production << 'EOF'
DATABASE_URL=file:/app/shuihu-release/db/custom.db
NODE_ENV=production
PORT=3000
HOSTNAME=0.0.0.0
NEXT_TELEMETRY_DISABLED=1
EOF
# 启动时加载
export $(cat .env.production | xargs)
bun .next/standalone/server.js
12. 常见问题排查
12.1 问题诊断流程
12.2 常见错误及解决方案
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
Cannot find module 'next' |
依赖未安装 | bun install |
PrismaClientInitializationError |
数据库路径错误 | 检查 DATABASE_URL 是否正确 |
EADDRINUSE :3000 |
端口被占用 | lsof -i :3000 查看并 kill 占用进程 |
ECONNREFUSED |
Caddy 未启动或 Next.js 未运行 | 按顺序启动 Next → Caddy |
| AI 返回空白 | LLM API 不可用 | 检查 API URL 和 Key，内置 SDK 可回退 |
| 数据库文件只读 | 权限问题 | chmod 644 db/custom.db |
| 构建失败 | 内存不足 | 增加 swap 或内存，使用 NODE_OPTIONS=--max-old-space-size=2048 |
12.3 日志查看
# Next.js 服务日志
tail -f server.log
# Caddy 日志
journalctl -u caddy -f
# 系统资源
top -p $(pgrep -f "bun server.js")
# 检查数据库完整性
sqlite3 db/custom.db "PRAGMA integrity_check;"
13. 运维脚本参考
13.1 systemd 服务配置
创建 /etc/systemd/system/shuihu.service：
[Unit]
Description=水浒传 AI江湖 Next.js Server
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/app/shuihu-release/next-service-dist
Environment=NODE_ENV=production
Environment=PORT=3000
Environment=HOSTNAME=0.0.0.0
Environment=DATABASE_URL=file:/app/shuihu-release/db/custom.db
ExecStart=/usr/local/bin/bun server.js
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
启动服务：
sudo systemctl daemon-reload
sudo systemctl enable shuihu
sudo systemctl start shuihu
sudo systemctl status shuihu
13.2 健康检查脚本
#!/bin/bash
# health-check.sh
NEXT_URL="http://localhost:3000"
CADDY_URL="http://localhost:81"
MAX_RETRIES=3
RETRY_INTERVAL=5
check_service() {
local url=$1
local name=$2
local retries=0
while [ $retries -lt $MAX_RETRIES ]; do
if curl -fsS --connect-timeout 5 --max-time 10 "$url" > /dev/null 2>&1; then
echo "✅ $name ($url) is healthy"
return 0
fi
retries=$((retries + 1))
echo "⚠️ $name check attempt $retries/$MAX_RETRIES failed, retrying in ${RETRY_INTERVAL}s..."
sleep $RETRY_INTERVAL
done
echo "❌ $name ($url) is DOWN after $MAX_RETRIES attempts"
return 1
}
check_service "$NEXT_URL" "Next.js"
check_service "$CADDY_URL" "Caddy"
13.3 自动部署脚本
#!/bin/bash
# auto-deploy.sh
set -e
RELEASE_DIR="/app/shuihu-release"
PACKAGE="$1"
if [ -z "$PACKAGE" ]; then
echo "Usage: $0 <package.tar.gz>"
exit 1
fi
echo "🚀 开始自动部署..."
# 1. 停止现有服务
echo "🛑 停止现有服务..."
sudo systemctl stop shuihu 2>/dev/null || true
caddy stop 2>/dev/null || true
# 2. 备份数据库
if [ -f "$RELEASE_DIR/db/custom.db" ]; then
echo "💾 备份数据库..."
cp "$RELEASE_DIR/db/custom.db" "/tmp/db_backup_$(date +%Y%m%d_%H%M%S).db"
fi
# 3. 解压新版本
echo "📦 解压新版本..."
rm -rf "$RELEASE_DIR"
mkdir -p "$RELEASE_DIR"
tar -xzf "$PACKAGE" -C "$RELEASE_DIR"
# 4. 启动服务
echo "▶️ 启动服务..."
cd "$RELEASE_DIR"
bash start.sh &
# 5. 等待启动
sleep 5
# 6. 健康检查
if curl -fsS --max-time 10 http://localhost:81 > /dev/null 2>&1; then
echo "✅ 部署成功！"
else
echo "❌ 部署后健康检查失败，请检查日志"
exit 1
fi
13.4 定时备份
# 添加到 crontab
# 每天凌晨 3 点备份数据库，保留最近 7 天
0 3 * * * cp /app/shuihu-release/db/custom.db /app/backups/db_$(date +\%Y\%m\%d).db && find /app/backups/ -name "db_*.db" -mtime +7 -delete
附录：部署清单速查
| 步骤 | 命令 | 预计耗时 |
|---|---|---|
| 安装 Bun | curl -fsSL https://bun.sh/install | bash |
30s |
| 安装 Caddy | sudo apt install caddy |
20s |
| 安装依赖 | bun install |
30-60s |
| 初始化数据库 | bun run db:push |
5s |
| 构建项目 | bun run build |
60-120s |
| 启动服务 | bun .next/standalone/server.js |
5s |
| 启动 Caddy | caddy run --config Caddyfile |
2s |
| 总计（首次部署） | 约 3-5 分钟 |
如有其他部署问题，请检查项目
agent-ctx/目录下的开发日志，或参考.zscripts/中的脚本实现细节。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
6
0- 0
已为社区贡献113条内容
所有评论(0)