first commit
This commit is contained in:
dekun
+458
@@ -0,0 +1,458 @@
|
||||
# 知命阁（zhimingge）Ubuntu 部署文档
|
||||
|
||||
> 仓库：[https://git.bz121.com/dekun/zhimingge.git](https://git.bz121.com/dekun/zhimingge.git)
|
||||
|
||||
本文档说明在 **Ubuntu 服务器**上使用 **root 用户**、**PM2** 将知命阁部署到 **`/opt/zhimingge`** 的完整流程。
|
||||
|
||||
---
|
||||
|
||||
## 1. 部署架构
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
用户浏览器 ──→ │ Nginx (可选) │ :80 / :443
|
||||
│ 反向代理 │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ PM2 │
|
||||
│ zhimingge │ :3000
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ Next.js │
|
||||
│ standalone │
|
||||
│ /opt/zhimingge │
|
||||
└─────────────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ op.bz121.com │ AI API
|
||||
│ /v1 │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
| 组件 | 说明 |
|
||||
|------|------|
|
||||
| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04 LTS |
|
||||
| 运行用户 | root（按需求） |
|
||||
| 安装目录 | `/opt/zhimingge` |
|
||||
| 进程管理 | PM2 |
|
||||
| 构建模式 | Next.js `output: "standalone"` |
|
||||
| 默认端口 | 3000 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 服务器要求
|
||||
|
||||
| 项目 | 最低配置 | 推荐配置 |
|
||||
|------|----------|----------|
|
||||
| CPU | 1 核 | 2 核 |
|
||||
| 内存 | 1 GB | 2 GB+ |
|
||||
| 磁盘 | 2 GB | 10 GB |
|
||||
| 网络 | 可访问 git.bz121.com、op.bz121.com | — |
|
||||
|
||||
---
|
||||
|
||||
## 3. 一次性环境准备
|
||||
|
||||
以 **root** 登录服务器后执行：
|
||||
|
||||
### 3.1 更新系统
|
||||
|
||||
```bash
|
||||
apt update && apt upgrade -y
|
||||
```
|
||||
|
||||
### 3.2 安装 Node.js 20（推荐 LTS）
|
||||
|
||||
```bash
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
|
||||
apt install -y nodejs
|
||||
node -v # 应 >= v20
|
||||
npm -v
|
||||
```
|
||||
|
||||
### 3.3 安装 pnpm 与 PM2
|
||||
|
||||
```bash
|
||||
npm install -g pnpm pm2
|
||||
pnpm -v
|
||||
pm2 -v
|
||||
```
|
||||
|
||||
### 3.4 安装 Git
|
||||
|
||||
```bash
|
||||
apt install -y git
|
||||
```
|
||||
|
||||
### 3.5（可选）安装 Nginx 反向代理
|
||||
|
||||
若需域名 + HTTPS，建议安装 Nginx 与 Certbot：
|
||||
|
||||
```bash
|
||||
apt install -y nginx certbot python3-certbot-nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 克隆与目录
|
||||
|
||||
```bash
|
||||
mkdir -p /opt
|
||||
cd /opt
|
||||
|
||||
# 首次克隆（私有仓库需配置凭据，见第 5 节）
|
||||
git clone https://git.bz121.com/dekun/zhimingge.git zhimingge
|
||||
|
||||
cd /opt/zhimingge
|
||||
```
|
||||
|
||||
最终目录：
|
||||
|
||||
```
|
||||
/opt/zhimingge/
|
||||
├── app/
|
||||
├── content/
|
||||
├── ecosystem.config.cjs
|
||||
├── .env.local ← 生产环境变量（勿提交 Git）
|
||||
├── package.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Git 凭据（私有仓库）
|
||||
|
||||
仓库 [dekun/zhimingge](https://git.bz121.com/dekun/zhimingge.git) 为私有仓库，克隆前需配置认证。
|
||||
|
||||
### 方式 A：HTTPS + 访问令牌（推荐）
|
||||
|
||||
```bash
|
||||
git config --global credential.helper store
|
||||
git clone https://git.bz121.com/dekun/zhimingge.git /opt/zhimingge
|
||||
# 按提示输入 Gitea 用户名与 Personal Access Token
|
||||
```
|
||||
|
||||
在 Gitea 生成 Token：用户设置 → Applications → Generate New Token（勾选 `repo` 权限）。
|
||||
|
||||
### 方式 B：SSH
|
||||
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -C "zhimingge-deploy" -f /root/.ssh/zhimingge -N ""
|
||||
cat /root/.ssh/zhimingge.pub
|
||||
# 将公钥添加到 Gitea → Settings → SSH Keys
|
||||
|
||||
cat >> /root/.ssh/config << 'EOF'
|
||||
Host git.bz121.com
|
||||
IdentityFile /root/.ssh/zhimingge
|
||||
StrictHostKeyChecking accept-new
|
||||
EOF
|
||||
|
||||
git clone git@git.bz121.com:dekun/zhimingge.git /opt/zhimingge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 环境变量
|
||||
|
||||
```bash
|
||||
cd /opt/zhimingge
|
||||
cp .env.example .env.local
|
||||
nano .env.local
|
||||
```
|
||||
|
||||
**`.env.local` 示例：**
|
||||
|
||||
```env
|
||||
# AI 接口（必填）
|
||||
OPENAI_API_KEY=你的密钥
|
||||
|
||||
# AI 地址与模型（已有默认值，可按需覆盖）
|
||||
OPENAI_BASE_URL=https://op.bz121.com/v1
|
||||
OPENAI_MODEL=huihui_ai/gemma-4-abliterated:e4b
|
||||
|
||||
# 服务端口
|
||||
PORT=3000
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
保存后限制权限：
|
||||
|
||||
```bash
|
||||
chmod 600 .env.local
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 构建与启动
|
||||
|
||||
### 7.1 安装依赖
|
||||
|
||||
```bash
|
||||
cd /opt/zhimingge
|
||||
pnpm install --frozen-lockfile
|
||||
```
|
||||
|
||||
### 7.2 生产构建
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
构建成功后生成 `.next/standalone/` 独立运行包。
|
||||
|
||||
### 7.3 复制静态资源（standalone 必需）
|
||||
|
||||
Next.js standalone 模式需手动链接静态文件：
|
||||
|
||||
```bash
|
||||
cd /opt/zhimingge
|
||||
|
||||
# 复制 static 与 public 到 standalone 目录
|
||||
cp -r .next/static .next/standalone/.next/static
|
||||
cp -r public .next/standalone/public
|
||||
|
||||
# 复制内容库（服务端读取卦辞 Markdown）
|
||||
cp -r content .next/standalone/content
|
||||
```
|
||||
|
||||
> **说明**：若应用从项目根目录读取 `content/`，PM2 的 `cwd` 应设为 `/opt/zhimingge` 而非 standalone 子目录。当前 `ecosystem.config.cjs` 使用项目根目录 + `pnpm start`，构建后也可改用 standalone 的 `server.js`（见 7.5 备选方案）。
|
||||
|
||||
### 7.4 使用 PM2 启动（推荐方式）
|
||||
|
||||
项目根目录已包含 `ecosystem.config.cjs`：
|
||||
|
||||
```bash
|
||||
cd /opt/zhimingge
|
||||
pm2 start ecosystem.config.cjs
|
||||
pm2 save
|
||||
pm2 startup
|
||||
# 按 PM2 提示执行生成的命令，确保开机自启
|
||||
```
|
||||
|
||||
常用 PM2 命令：
|
||||
|
||||
```bash
|
||||
pm2 status # 查看状态
|
||||
pm2 logs zhimingge # 查看日志
|
||||
pm2 restart zhimingge # 重启
|
||||
pm2 stop zhimingge # 停止
|
||||
pm2 delete zhimingge # 删除进程
|
||||
```
|
||||
|
||||
### 7.5 备选：standalone 直接运行
|
||||
|
||||
若希望仅运行 standalone 产物（体积更小）：
|
||||
|
||||
```bash
|
||||
cd /opt/zhimingge/.next/standalone
|
||||
PORT=3000 node server.js
|
||||
```
|
||||
|
||||
对应 PM2 配置片段：
|
||||
|
||||
```javascript
|
||||
{
|
||||
name: "zhimingge",
|
||||
cwd: "/opt/zhimingge/.next/standalone",
|
||||
script: "server.js",
|
||||
env: {
|
||||
PORT: 3000,
|
||||
NODE_ENV: "production",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
此时需确保 `content/`、`public/` 路径在代码中相对于 `cwd` 可访问。
|
||||
|
||||
### 7.6 验证
|
||||
|
||||
```bash
|
||||
curl -I http://127.0.0.1:3000
|
||||
# 应返回 HTTP/1.1 200
|
||||
```
|
||||
|
||||
浏览器访问：`http://服务器IP:3000`
|
||||
|
||||
---
|
||||
|
||||
## 8. Nginx 反向代理（可选）
|
||||
|
||||
假设域名为 `zhimingge.example.com`：
|
||||
|
||||
```bash
|
||||
nano /etc/nginx/sites-available/zhimingge
|
||||
```
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name zhimingge.example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
|
||||
# AI 流式响应需禁用缓冲
|
||||
proxy_buffering off;
|
||||
proxy_read_timeout 300s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
ln -s /etc/nginx/sites-available/zhimingge /etc/nginx/sites-enabled/
|
||||
nginx -t
|
||||
systemctl reload nginx
|
||||
|
||||
# HTTPS（Let's Encrypt）
|
||||
certbot --nginx -d zhimingge.example.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 更新部署流程
|
||||
|
||||
代码推送至 Gitea 后，在服务器执行：
|
||||
|
||||
```bash
|
||||
cd /opt/zhimingge
|
||||
|
||||
# 拉取最新代码
|
||||
git pull origin main
|
||||
|
||||
# 安装新依赖（如有变更）
|
||||
pnpm install --frozen-lockfile
|
||||
|
||||
# 重新构建
|
||||
pnpm run build
|
||||
|
||||
# 若使用 standalone 复制方式，重新复制 static/public/content
|
||||
cp -r .next/static .next/standalone/.next/static
|
||||
cp -r public .next/standalone/public
|
||||
cp -r content .next/standalone/content
|
||||
|
||||
# 重启
|
||||
pm2 restart zhimingge
|
||||
```
|
||||
|
||||
可写入脚本 `/opt/zhimingge/scripts/deploy.sh` 一键执行（见项目内脚本）。
|
||||
|
||||
---
|
||||
|
||||
## 10. 防火墙
|
||||
|
||||
若使用 UFW：
|
||||
|
||||
```bash
|
||||
# 仅 Nginx 对外（推荐）
|
||||
ufw allow 22
|
||||
ufw allow 80
|
||||
ufw allow 443
|
||||
ufw enable
|
||||
|
||||
# 若不用 Nginx，直接暴露 3000
|
||||
ufw allow 3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 日志与排错
|
||||
|
||||
### PM2 日志
|
||||
|
||||
```bash
|
||||
pm2 logs zhimingge --lines 100
|
||||
```
|
||||
|
||||
日志文件位置（默认）：
|
||||
|
||||
```
|
||||
/root/.pm2/logs/zhimingge-out.log
|
||||
/root/.pm2/logs/zhimingge-error.log
|
||||
```
|
||||
|
||||
### 常见问题
|
||||
|
||||
| 现象 | 可能原因 | 处理 |
|
||||
|------|----------|------|
|
||||
| 502 Bad Gateway | PM2 进程未运行 | `pm2 restart zhimingge` |
|
||||
| AI 解读失败 | API Key 错误或模型名不对 | 检查 `.env.local` |
|
||||
| 卦辞读取失败 | `content/` 路径不存在 | 确认 `content/zhouyi/docs/` 存在 |
|
||||
| 构建 OOM | 内存不足 | 增加 swap 或升级内存 |
|
||||
| 流式输出中断 | Nginx 缓冲 | 设置 `proxy_buffering off` |
|
||||
| Git pull 失败 | 凭据过期 | 重新配置 Token 或 SSH |
|
||||
|
||||
### 构建内存不足时增加 Swap
|
||||
|
||||
```bash
|
||||
fallocate -l 2G /swapfile
|
||||
chmod 600 /swapfile
|
||||
mkswap /swapfile
|
||||
swapon /swapfile
|
||||
echo '/swapfile none swap sw 0 0' >> /etc/fstab
|
||||
```
|
||||
|
||||
### 测试 AI 接口
|
||||
|
||||
```bash
|
||||
curl https://op.bz121.com/v1/models \
|
||||
-H "Authorization: Bearer 你的OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
确认返回列表中包含 `huihui_ai/gemma-4-abliterated:e4b`。
|
||||
|
||||
---
|
||||
|
||||
## 12. 安全建议
|
||||
|
||||
虽然当前按 **root** 部署，仍建议：
|
||||
|
||||
1. **`.env.local` 权限** 设为 `600`，勿提交 Git
|
||||
2. **API Key** 仅保存在服务器，不要写入前端代码
|
||||
3. 生产环境使用 **Nginx + HTTPS**
|
||||
4. 定期 `apt update` 与 `pnpm update`
|
||||
5. 若后续改为非 root 运行，创建专用用户：
|
||||
|
||||
```bash
|
||||
useradd -r -s /bin/false zhimingge
|
||||
chown -R zhimingge:zhimingge /opt/zhimingge
|
||||
# PM2 中以 zhimingge 用户启动
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. 快速命令参考
|
||||
|
||||
```bash
|
||||
# 完整首次部署
|
||||
cd /opt && git clone https://git.bz121.com/dekun/zhimingge.git zhimingge
|
||||
cd /opt/zhimingge
|
||||
cp .env.example .env.local && nano .env.local
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm run build
|
||||
pm2 start ecosystem.config.cjs
|
||||
pm2 save && pm2 startup
|
||||
|
||||
# 日常更新
|
||||
cd /opt/zhimingge && git pull && pnpm install && pnpm run build && pm2 restart zhimingge
|
||||
|
||||
# 查看状态
|
||||
pm2 status && curl -I http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 相关文档
|
||||
|
||||
- 产品说明：[docs/SPEC.md](./SPEC.md)
|
||||
- 环境变量示例：[../.env.example](../.env.example)
|
||||
- PM2 配置：[../ecosystem.config.cjs](../ecosystem.config.cjs)
|
||||
Reference in New Issue
Block a user