774 lines
20 KiB
Markdown
774 lines
20 KiB
Markdown
# PandaWiki Ubuntu 22.04 内网部署指南
|
||
|
||
本文档涵盖从源码传输、构建 Docker 镜像到部署运行的完整流程。
|
||
|
||
---
|
||
|
||
## 一、整体部署架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────┐
|
||
│ Ubuntu 22.04 Server │
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ Nginx/Caddy │ │ Admin 前端 │ │
|
||
│ │ (反向代理) │ │ (Nginx) │ │
|
||
│ │ 端口: 80/443│ │ 端口: 5000 │ │
|
||
│ └──────┬──────┘ └─────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────────┐ │
|
||
│ │ API 服务 (Go) │ 端口: 8000 │
|
||
│ │ Consumer 服务 (Go) │ 后台异步任务 │
|
||
│ └──────────┬───────────┘ │
|
||
│ │ │ │ │ │
|
||
│ ▼ ▼ ▼ ▼ │
|
||
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
|
||
│ │ PG │ │Redis │ │ NATS │ │MinIO │ │
|
||
│ │ :5432│ │:6379 │ │:4222 │ │:9000 │ │
|
||
│ └──────┘ └──────┘ └──────┘ └──────┘ │
|
||
│ │
|
||
│ ┌──────────────────────┐ │
|
||
│ │ RAG 向量检索服务 │ 端口: 5050 │
|
||
│ └──────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────┐ │
|
||
│ │ AI 大模型 API │ 外部配置 │
|
||
│ └──────────────────────┘ │
|
||
└──────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、服务器环境准备
|
||
|
||
### 2.1 系统要求
|
||
|
||
```bash
|
||
# 确认系统版本
|
||
lsb_release -a
|
||
# Ubuntu 22.04.x LTS
|
||
|
||
# 建议配置
|
||
# CPU: 4 核以上
|
||
# 内存: 8 GB 以上 (AI 相关功能需要更多)
|
||
# 磁盘: 50 GB 以上
|
||
```
|
||
|
||
### 2.2 安装 Docker
|
||
|
||
```bash
|
||
# 卸载旧版本 (如果有)
|
||
sudo apt-get remove docker docker-engine docker.io containerd runc
|
||
|
||
# 安装依赖
|
||
sudo apt-get update
|
||
sudo apt-get install -y \
|
||
ca-certificates \
|
||
curl \
|
||
gnupg \
|
||
lsb-release
|
||
|
||
# 添加 Docker 官方 GPG 密钥
|
||
sudo mkdir -p /etc/apt/keyrings
|
||
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
|
||
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
||
|
||
# 添加 Docker 仓库
|
||
echo \
|
||
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
|
||
https://download.docker.com/linux/ubuntu \
|
||
$(lsb_release -cs) stable" | \
|
||
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||
|
||
# 安装 Docker Engine
|
||
sudo apt-get update
|
||
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
|
||
docker-buildx-plugin docker-compose-plugin
|
||
|
||
# 验证安装
|
||
sudo docker --version
|
||
sudo docker compose version
|
||
|
||
# 将当前用户加入 docker 组 (免 sudo)
|
||
sudo usermod -aG docker $USER
|
||
newgrp docker
|
||
|
||
# 设置 Docker 开机自启
|
||
sudo systemctl enable docker
|
||
```
|
||
|
||
### 2.3 安装 Docker Compose (独立版，可选)
|
||
|
||
Docker 新版已内置 `docker compose` 插件。如需独立版：
|
||
|
||
```bash
|
||
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
|
||
-o /usr/local/bin/docker-compose
|
||
sudo chmod +x /usr/local/bin/docker-compose
|
||
```
|
||
|
||
### 2.4 安装 Git (用于获取源码)
|
||
|
||
```bash
|
||
sudo apt-get install -y git
|
||
```
|
||
|
||
---
|
||
|
||
## 三、传输源码到服务器
|
||
|
||
### 方式 A：Git 仓库 (服务器有网络)
|
||
|
||
```bash
|
||
# 在服务器上
|
||
git clone https://github.com/chaitin/PandaWiki.git
|
||
cd PandaWiki
|
||
|
||
# 然后将你 Windows 上修改过的文件传输到服务器覆盖对应文件
|
||
# 需要覆盖的文件：
|
||
# backend/domain/license.go
|
||
# backend/usecase/stat.go
|
||
# backend/repo/pg/auth.go
|
||
# web/admin/src/constant/version.ts
|
||
```
|
||
|
||
### 方式 B：直接 SCP 传输整个项目 (推荐)
|
||
|
||
在 Windows 上使用 PowerShell 或 WSL：
|
||
|
||
```powershell
|
||
# 在 Windows 上执行，将整个项目传到服务器
|
||
scp -r "E:\code project\PandaWiki-3.85.0" user@your-server-ip:/home/user/
|
||
|
||
# 或者用 rsync (WSL/Linux)
|
||
rsync -avz --progress \
|
||
"/mnt/e/code project/PandaWiki-3.85.0/" \
|
||
user@your-server-ip:/home/user/PandaWiki/
|
||
```
|
||
|
||
### 方式 C：打包传输
|
||
|
||
```bash
|
||
# 在 Windows 上打包 (Git Bash / WSL)
|
||
cd "E:\code project\PandaWiki-3.85.0"
|
||
tar --exclude='.git' -czf panda-wiki.tar.gz .
|
||
|
||
# 传输到服务器
|
||
scp panda-wiki.tar.gz user@your-server-ip:/home/user/
|
||
|
||
# 在服务器上解压
|
||
mkdir -p ~/PandaWiki && cd ~/PandaWiki
|
||
tar -xzf ~/panda-wiki.tar.gz
|
||
```
|
||
|
||
---
|
||
|
||
## 四、创建 Docker Compose 配置
|
||
|
||
在项目根目录创建 `docker-compose.yml`：
|
||
|
||
```bash
|
||
cd ~/PandaWiki
|
||
```
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
version: '3.8'
|
||
|
||
services:
|
||
# ========== 基础设施 ==========
|
||
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
container_name: panda-wiki-postgres
|
||
restart: unless-stopped
|
||
environment:
|
||
POSTGRES_USER: panda-wiki
|
||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-ChangeMe123!}
|
||
POSTGRES_DB: panda-wiki
|
||
volumes:
|
||
- pg_data:/var/lib/postgresql/data
|
||
ports:
|
||
- "127.0.0.1:5432:5432"
|
||
healthcheck:
|
||
test: ["CMD-SHELL", "pg_isready -U panda-wiki"]
|
||
interval: 5s
|
||
timeout: 5s
|
||
retries: 5
|
||
networks:
|
||
- panda-wiki
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
container_name: panda-wiki-redis
|
||
restart: unless-stopped
|
||
command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD:-ChangeMe123!}
|
||
volumes:
|
||
- redis_data:/data
|
||
ports:
|
||
- "127.0.0.1:6379:6379"
|
||
healthcheck:
|
||
test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
|
||
interval: 5s
|
||
timeout: 5s
|
||
retries: 5
|
||
networks:
|
||
- panda-wiki
|
||
|
||
nats:
|
||
image: nats:2-alpine
|
||
container_name: panda-wiki-nats
|
||
restart: unless-stopped
|
||
command: >
|
||
-js
|
||
-m 8222
|
||
--user ${NATS_USER:-panda-wiki}
|
||
--pass ${NATS_PASSWORD:-ChangeMe123!}
|
||
ports:
|
||
- "127.0.0.1:4222:4222"
|
||
- "127.0.0.1:8222:8222"
|
||
networks:
|
||
- panda-wiki
|
||
|
||
minio:
|
||
image: minio/minio:latest
|
||
container_name: panda-wiki-minio
|
||
restart: unless-stopped
|
||
command: server /data --console-address ":9001"
|
||
environment:
|
||
MINIO_ROOT_USER: ${S3_ACCESS_KEY:-s3panda-wiki}
|
||
MINIO_ROOT_PASSWORD: ${S3_SECRET_KEY:-ChangeMe123!}
|
||
volumes:
|
||
- minio_data:/data
|
||
ports:
|
||
- "127.0.0.1:9000:9000"
|
||
- "127.0.0.1:9001:9001"
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 5
|
||
networks:
|
||
- panda-wiki
|
||
|
||
# ========== 业务服务 ==========
|
||
|
||
api:
|
||
build:
|
||
context: ./backend
|
||
dockerfile: Dockerfile.api
|
||
image: panda-wiki-api:latest
|
||
container_name: panda-wiki-api
|
||
restart: unless-stopped
|
||
environment:
|
||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-ChangeMe123!}
|
||
NATS_PASSWORD: ${NATS_PASSWORD:-ChangeMe123!}
|
||
REDIS_PASSWORD: ${REDIS_PASSWORD:-ChangeMe123!}
|
||
JWT_SECRET: ${JWT_SECRET:-your-jwt-secret-change-me}
|
||
S3_SECRET_KEY: ${S3_SECRET_KEY:-ChangeMe123!}
|
||
ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin123}
|
||
LOG_LEVEL: ${LOG_LEVEL:-0}
|
||
ENV: ${ENV:-production}
|
||
SENTRY_ENABLED: "false"
|
||
PG_DSN: "host=panda-wiki-postgres user=panda-wiki password=${POSTGRES_PASSWORD:-ChangeMe123!} dbname=panda-wiki port=5432 sslmode=disable TimeZone=Asia/Shanghai"
|
||
MQ_NATS_SERVER: "nats://panda-wiki-nats:4222"
|
||
REDIS_ADDR: "panda-wiki-redis:6379"
|
||
S3_ENDPOINT: "panda-wiki-minio:9000"
|
||
RAG_CT_RAG_BASE_URL: ${RAG_BASE_URL:-http://host.docker.internal:5050}
|
||
ports:
|
||
- "127.0.0.1:8000:8000"
|
||
depends_on:
|
||
postgres:
|
||
condition: service_healthy
|
||
redis:
|
||
condition: service_healthy
|
||
nats:
|
||
condition: service_started
|
||
minio:
|
||
condition: service_healthy
|
||
networks:
|
||
- panda-wiki
|
||
|
||
consumer:
|
||
build:
|
||
context: ./backend
|
||
dockerfile: Dockerfile.consumer
|
||
image: panda-wiki-consumer:latest
|
||
container_name: panda-wiki-consumer
|
||
restart: unless-stopped
|
||
environment:
|
||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-ChangeMe123!}
|
||
NATS_PASSWORD: ${NATS_PASSWORD:-ChangeMe123!}
|
||
REDIS_PASSWORD: ${REDIS_PASSWORD:-ChangeMe123!}
|
||
JWT_SECRET: ${JWT_SECRET:-your-jwt-secret-change-me}
|
||
S3_SECRET_KEY: ${S3_SECRET_KEY:-ChangeMe123!}
|
||
LOG_LEVEL: ${LOG_LEVEL:-0}
|
||
ENV: ${ENV:-production}
|
||
SENTRY_ENABLED: "false"
|
||
PG_DSN: "host=panda-wiki-postgres user=panda-wiki password=${POSTGRES_PASSWORD:-ChangeMe123!} dbname=panda-wiki port=5432 sslmode=disable TimeZone=Asia/Shanghai"
|
||
MQ_NATS_SERVER: "nats://panda-wiki-nats:4222"
|
||
REDIS_ADDR: "panda-wiki-redis:6379"
|
||
S3_ENDPOINT: "panda-wiki-minio:9000"
|
||
RAG_CT_RAG_BASE_URL: ${RAG_BASE_URL:-http://host.docker.internal:5050}
|
||
depends_on:
|
||
postgres:
|
||
condition: service_healthy
|
||
redis:
|
||
condition: service_healthy
|
||
nats:
|
||
condition: service_started
|
||
minio:
|
||
condition: service_healthy
|
||
networks:
|
||
- panda-wiki
|
||
|
||
# Nginx 反向代理 (可选，用于统一入口)
|
||
nginx:
|
||
image: nginx:alpine
|
||
container_name: panda-wiki-nginx
|
||
restart: unless-stopped
|
||
volumes:
|
||
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
|
||
ports:
|
||
- "80:80"
|
||
depends_on:
|
||
- api
|
||
networks:
|
||
- panda-wiki
|
||
|
||
volumes:
|
||
pg_data:
|
||
redis_data:
|
||
minio_data:
|
||
|
||
networks:
|
||
panda-wiki:
|
||
driver: bridge
|
||
```
|
||
|
||
### 创建 Nginx 反向代理配置
|
||
|
||
```bash
|
||
cat > nginx.conf << 'EOF'
|
||
server {
|
||
listen 80;
|
||
server_name _;
|
||
client_max_body_size 100M;
|
||
|
||
# API 服务
|
||
location /api/ {
|
||
proxy_pass http://panda-wiki-api:8000;
|
||
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;
|
||
}
|
||
|
||
location /share/ {
|
||
proxy_pass http://panda-wiki-api:8000;
|
||
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;
|
||
}
|
||
|
||
# 健康检查
|
||
location /health {
|
||
proxy_pass http://panda-wiki-api:8000;
|
||
}
|
||
}
|
||
EOF
|
||
```
|
||
|
||
### 创建环境变量文件
|
||
|
||
```bash
|
||
cat > .env << 'EOF'
|
||
# 数据库密码
|
||
POSTGRES_PASSWORD=ChangeMe123!
|
||
|
||
# Redis 密码
|
||
REDIS_PASSWORD=ChangeMe123!
|
||
|
||
# NATS 密码
|
||
NATS_USER=panda-wiki
|
||
NATS_PASSWORD=ChangeMe123!
|
||
|
||
# MinIO/S3
|
||
S3_ACCESS_KEY=s3panda-wiki
|
||
S3_SECRET_KEY=ChangeMe123!
|
||
|
||
# JWT 密钥 (务必修改为随机字符串)
|
||
JWT_SECRET=your-jwt-secret-change-me-to-random-string
|
||
|
||
# 管理员初始密码 (首次登录后修改)
|
||
ADMIN_PASSWORD=admin123
|
||
|
||
# 日志级别: -4=debug, 0=info, 4=warn, 8=error
|
||
LOG_LEVEL=0
|
||
|
||
# RAG 向量检索服务地址
|
||
RAG_BASE_URL=http://host.docker.internal:5050
|
||
EOF
|
||
```
|
||
|
||
---
|
||
|
||
## 五、构建并启动
|
||
|
||
### 5.1 构建后端 Docker 镜像
|
||
|
||
```bash
|
||
cd ~/PandaWiki
|
||
|
||
# 构建 API 镜像 (包含数据库迁移)
|
||
docker build -f backend/Dockerfile.api -t panda-wiki-api:latest ./backend
|
||
|
||
# 构建 Consumer 镜像
|
||
docker build -f backend/Dockerfile.consumer -t panda-wiki-consumer:latest ./backend
|
||
```
|
||
|
||
### 5.2 构建前端 (可选)
|
||
|
||
如果需要在服务器上运行前端：
|
||
|
||
```bash
|
||
# 安装 Node.js 22 (管理员前端构建)
|
||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
|
||
# 安装 pnpm
|
||
sudo npm install -g pnpm
|
||
|
||
# 构建管理员前端
|
||
cd ~/PandaWiki/web
|
||
pnpm install
|
||
pnpm --filter panda-wiki-admin build
|
||
|
||
# 构建用户端前端
|
||
pnpm --filter panda-wiki-app build
|
||
|
||
# 管理员前端会输出到 web/admin/dist/
|
||
# 用户端前端会输出到 web/app/dist/
|
||
# 可以用 Nginx 托管这些静态文件
|
||
```
|
||
|
||
### 5.3 启动全部服务
|
||
|
||
```bash
|
||
cd ~/PandaWiki
|
||
|
||
# 先启动基础设施
|
||
docker compose up -d postgres redis nats minio
|
||
|
||
# 等待基础设施就绪
|
||
sleep 15
|
||
|
||
# 启动业务服务
|
||
docker compose up -d api consumer nginx
|
||
|
||
# 查看所有容器状态
|
||
docker compose ps
|
||
|
||
# 查看日志
|
||
docker compose logs -f api
|
||
```
|
||
|
||
### 5.4 验证部署
|
||
|
||
```bash
|
||
# 检查 API 是否正常
|
||
curl http://localhost:8000/api/v1/health
|
||
|
||
# 查看容器日志
|
||
docker compose logs api | tail -50
|
||
docker compose logs consumer | tail -50
|
||
|
||
# 确认数据库迁移成功
|
||
docker compose logs api | grep -i migrate
|
||
```
|
||
|
||
---
|
||
|
||
## 六、AI 模型配置
|
||
|
||
首次登录管理后台后，需要配置 AI 大模型才能使用 AI 创作、AI 问答等功能。
|
||
|
||
### 支持的模型接入方式
|
||
|
||
| 方式 | 说明 |
|
||
|------|------|
|
||
| OpenAI 兼容 API | 任何兼容 OpenAI 接口的模型服务 |
|
||
| 本地 Ollama | 在内网服务器上自建 Ollama 服务 |
|
||
| DeepSeek API | DeepSeek 官方 API |
|
||
| Gemini API | Google Gemini |
|
||
|
||
### 内网环境推荐：自建 Ollama
|
||
|
||
```bash
|
||
# 在服务器上安装 Ollama
|
||
curl -fsSL https://ollama.com/install.sh | sh
|
||
|
||
# 拉取模型 (根据服务器配置选择)
|
||
ollama pull qwen2.5:7b # 7B 参数，需要约 8GB 显存/内存
|
||
ollama pull qwen2.5:14b # 14B 参数
|
||
ollama pull llama3.1:8b # 8B 参数
|
||
|
||
# Ollama API 默认监听 11434 端口
|
||
# 在 PandaWiki 管理后台配置模型时，填写：
|
||
# API 地址: http://host.docker.internal:11434/v1
|
||
# 模型名称: qwen2.5:7b
|
||
```
|
||
|
||
---
|
||
|
||
## 七、Nginx 前端托管 (可选)
|
||
|
||
将构建好的前端静态文件用 Nginx 托管：
|
||
|
||
```bash
|
||
# 创建前端部署目录
|
||
sudo mkdir -p /var/www/panda-wiki/{admin,app}
|
||
|
||
# 复制构建产物
|
||
sudo cp -r ~/PandaWiki/web/admin/dist/* /var/www/panda-wiki/admin/
|
||
sudo cp -r ~/PandaWiki/web/app/dist/* /var/www/panda-wiki/app/
|
||
|
||
# Nginx 配置
|
||
sudo tee /etc/nginx/sites-available/panda-wiki << 'EOF'
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
client_max_body_size 100M;
|
||
|
||
# 管理后台
|
||
location /admin {
|
||
alias /var/www/panda-wiki/admin;
|
||
index index.html;
|
||
try_files $uri $uri/ /admin/index.html;
|
||
}
|
||
|
||
# Wiki 用户端
|
||
location / {
|
||
root /var/www/panda-wiki/app;
|
||
index index.html;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# API 代理
|
||
location /api/ {
|
||
proxy_pass http://127.0.0.1:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
|
||
location /share/ {
|
||
proxy_pass http://127.0.0.1:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
}
|
||
EOF
|
||
|
||
sudo ln -s /etc/nginx/sites-available/panda-wiki /etc/nginx/sites-enabled/
|
||
sudo nginx -t
|
||
sudo systemctl reload nginx
|
||
```
|
||
|
||
---
|
||
|
||
## 八、内网完全离线部署
|
||
|
||
如果服务器**完全无法访问外网**，需要在有网络的机器上预先准备所有材料。
|
||
|
||
### 8.1 准备阶段 (在有网络的机器上)
|
||
|
||
```bash
|
||
# 1. 拉取所有基础 Docker 镜像
|
||
docker pull postgres:16-alpine
|
||
docker pull redis:7-alpine
|
||
docker pull nats:2-alpine
|
||
docker pull minio/minio:latest
|
||
docker pull nginx:alpine
|
||
docker pull golang:1.24.3-alpine
|
||
docker pull alpine:3.21
|
||
|
||
# 2. 导出镜像为 tar 文件
|
||
docker save -o postgres-16.tar postgres:16-alpine
|
||
docker save -o redis-7.tar redis:7-alpine
|
||
docker save -o nats-2.tar nats:2-alpine
|
||
docker save -o minio-latest.tar minio/minio:latest
|
||
docker save -o nginx-alpine.tar nginx:alpine
|
||
docker save -o golang-1.24.tar golang:1.24.3-alpine
|
||
docker save -o alpine-3.21.tar alpine:3.21
|
||
|
||
# 3. 下载 Go 依赖 (可选，Docker 构建时会自动处理)
|
||
# 如果有网络，直接 Docker build 即可
|
||
# 如果完全离线，需要预先 go mod download 并复制缓存
|
||
|
||
# 4. 打包项目源码
|
||
cd ~/PandaWiki
|
||
tar czf panda-wiki-source.tar.gz \
|
||
--exclude='.git' \
|
||
--exclude='node_modules' \
|
||
--exclude='web/.pnpm-store' \
|
||
.
|
||
|
||
# 5. 将镜像 tar 和源码 tar 传输到内网服务器
|
||
scp *.tar user@internal-server:/home/user/
|
||
```
|
||
|
||
### 8.2 部署阶段 (在内网服务器上)
|
||
|
||
```bash
|
||
# 1. 导入 Docker 镜像
|
||
cd /home/user
|
||
for f in *.tar; do
|
||
docker load -i "$f"
|
||
done
|
||
|
||
# 2. 解压项目源码
|
||
mkdir -p ~/PandaWiki && cd ~/PandaWiki
|
||
tar xzf ~/panda-wiki-source.tar.gz
|
||
|
||
# 3. 修改 docker-compose.yml 中的 build 部分
|
||
# 将 BUILDKIT 缓存挂载移除 (离线环境不支持)
|
||
# 将 Dockerfile 中的 --mount=type=cache 替换为普通 COPY
|
||
|
||
# 4. 创建离线版 Dockerfile
|
||
cat > backend/Dockerfile.api.offline << 'DOCKERFILE'
|
||
FROM golang:1.24.3-alpine AS builder
|
||
WORKDIR /src
|
||
ENV CGO_ENABLED=0
|
||
COPY backend/go.mod backend/go.sum ./
|
||
RUN go mod download
|
||
COPY backend/ .
|
||
ARG TARGETOS TARGETARCH VERSION
|
||
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build \
|
||
-ldflags "-s -w -extldflags '-static'" \
|
||
-o /build/panda-wiki-api \
|
||
cmd/api/main.go cmd/api/wire_gen.go \
|
||
&& GOOS=$TARGETOS GOARCH=$TARGETARCH go build \
|
||
-ldflags "-s -w -extldflags '-static'" \
|
||
-o /build/panda-wiki-migrate \
|
||
cmd/migrate/main.go cmd/migrate/wire_gen.go
|
||
|
||
FROM alpine:3.21 AS api
|
||
RUN apk update && apk upgrade && apk add --no-cache ca-certificates tzdata \
|
||
&& update-ca-certificates 2>/dev/null || true && rm -rf /var/cache/apk/*
|
||
WORKDIR /app
|
||
COPY --from=builder /build/panda-wiki-api /app/panda-wiki-api
|
||
COPY --from=builder /build/panda-wiki-migrate /app/panda-wiki-migrate
|
||
COPY --from=builder /src/store/pg/migration /app/migration
|
||
CMD ["sh", "-c", "/app/panda-wiki-migrate && /app/panda-wiki-api"]
|
||
DOCKERFILE
|
||
|
||
# 5. 使用离线 Dockerfile 构建
|
||
docker build -f backend/Dockerfile.api.offline -t panda-wiki-api:latest .
|
||
|
||
# 6. 启动服务
|
||
docker compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 九、常用运维命令
|
||
|
||
```bash
|
||
# 查看所有服务状态
|
||
docker compose ps
|
||
|
||
# 查看某个服务的实时日志
|
||
docker compose logs -f api
|
||
docker compose logs -f consumer
|
||
|
||
# 重启某个服务
|
||
docker compose restart api
|
||
|
||
# 进入容器调试
|
||
docker exec -it panda-wiki-api sh
|
||
|
||
# 数据库备份
|
||
docker exec panda-wiki-postgres pg_dump -U panda-wiki panda-wiki > backup.sql
|
||
|
||
# 数据库恢复
|
||
docker exec -i panda-wiki-postgres psql -U panda-wiki panda-wiki < backup.sql
|
||
|
||
# 更新代码后重新构建
|
||
docker compose build api consumer
|
||
docker compose up -d api consumer
|
||
|
||
# 查看资源占用
|
||
docker stats
|
||
|
||
# 完全停止
|
||
docker compose down
|
||
|
||
# 停止并删除数据卷 (危险！会丢失所有数据)
|
||
docker compose down -v
|
||
```
|
||
|
||
---
|
||
|
||
## 十、访问地址
|
||
|
||
部署完成后：
|
||
|
||
| 地址 | 说明 |
|
||
|------|------|
|
||
| `http://服务器IP:8000` | 后端 API (通过 Nginx 代理则为 80 端口) |
|
||
| `http://服务器IP:2443` | 管理后台 (如使用官方 Caddy 配置) |
|
||
| `http://服务器IP:9001` | MinIO 管理控制台 |
|
||
|
||
首次登录使用 `.env` 中配置的 `ADMIN_PASSWORD` 密码，用户名为 `admin`。
|
||
|
||
---
|
||
|
||
## 十一、故障排查
|
||
|
||
### 数据库连接失败
|
||
|
||
```bash
|
||
# 检查 postgres 是否就绪
|
||
docker compose logs postgres
|
||
|
||
# 手动连接测试
|
||
docker exec -it panda-wiki-postgres psql -U panda-wiki -d panda-wiki
|
||
```
|
||
|
||
### API 启动失败
|
||
|
||
```bash
|
||
# 查看详细日志
|
||
docker compose logs api
|
||
|
||
# 常见原因：
|
||
# 1. 数据库迁移失败 - 检查 PG_DSN 配置
|
||
# 2. NATS 连接失败 - 检查 MQ_NATS_SERVER 配置
|
||
# 3. Redis 连接失败 - 检查 REDIS_ADDR 配置
|
||
```
|
||
|
||
### 前端页面空白
|
||
|
||
```bash
|
||
# 检查 API 是否可达
|
||
curl http://localhost:8000/api/v1/health
|
||
|
||
# 检查浏览器控制台是否有 CORS 或 API 404 错误
|
||
# 确保前端配置的 API 地址正确
|
||
```
|
||
|
||
### 容器之间网络不通
|
||
|
||
```bash
|
||
# 检查网络
|
||
docker network inspect panda-wiki_panda-wiki
|
||
|
||
# 容器间通信测试
|
||
docker exec panda-wiki-api ping panda-wiki-postgres
|
||
```
|