YouduWiki/SELF_BUILD_GUIDE.md

# PandaWiki 自行构建部署指南 (功能全解锁版)

## 修改说明

本文档记录了将所有商业订阅限制移除的修改，改后开源版功能等同商业版。

### 已修改的文件 (共 5 个)

| 文件 | 修改内容 |
|------|---------|
| `backend/domain/license.go` | 将所有 `Allow*` 设为 `true`，所有 `Max*` 设为 999999 |
| `backend/usecase/stat.go` | 移除统计天数的版本校验 (1/7/30/90 天全部开放) |
| `backend/repo/pg/auth.go` | 移除 SSO 认证的速率限制 |
| `web/admin/src/constant/version.ts` | Free 版功能映射改为等同企业版，权限数组包含 Free 版 |
| `SELF_BUILD_GUIDE.md` | 本文档 |

### 具体修改详情

#### 1. `backend/domain/license.go` — 默认限制解除

```go
var baseEditionLimitationDefault = BaseEditionLimitation{
    MaxKb:                  999999,  // 原 1
    MaxNode:                999999,  // 原 300
    MaxSSOUser:             999999,  // 原 0
    MaxAdmin:               999999,  // 原 1
    AllowAdminPerm:         true,    // 原 false
    AllowCustomCopyright:   true,    // 原 false
    AllowCommentAudit:      true,    // 原 false
    AllowAdvancedBot:       true,    // 原 false
    AllowWatermark:         true,    // 原 false
    AllowCopyProtection:    true,    // 原 false
    AllowOpenAIBotSettings: true,    // 原 false
    AllowMCPServer:         true,    // 原 false
    AllowNodeStats:         true,    // 原 false
}
```

#### 2. `backend/usecase/stat.go` — 统计天数全开放

移除了 `ValidateStatDay` 中的版本判断，1天/7天/30天/90天统计对所有版本开放。

#### 3. `backend/repo/pg/auth.go` — SSO 速率限制移除

移除了 GetOrCreateAuth 中对非企业版的速率限制。

#### 4. `web/admin/src/constant/version.ts` — 前端功能映射

- `PROFESSION_VERSION_PERMISSION` 和 `BUSINESS_VERSION_PERMISSION` 数组中加入 `LicenseEditionFree`
- `VERSION_INFO[LicenseEditionFree].features` 所有功能设为 `SUPPORTED` / `ADVANCED`，数量限制设为 `Infinity`

---

## 架构总览

```
┌─────────────────────────────────────────────────────┐
│                    用户浏览器                         │
├──────────────────────┬──────────────────────────────┤
│  管理后台 (Admin)     │  知识库网站 (App)              │
│  React + Vite        │  Next.js 16                  │
│  端口: 5173 (dev)     │  端口: 3010 (dev)             │
└──────────────────────┴──────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              后端 API (Go / Echo)                     │
│  端口: 8000                                          │
│  - /api/v1/*   (管理 API)                            │
│  - /share/v1/* (前端网站 API)                         │
└──────────────────────┬──────────────────────────────┘
         │              │           │           │
         ▼              ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │  Redis   │ │  NATS    │ │  MinIO   │
│  数据库   │ │  缓存    │ │ 消息队列  │ │ 文件存储  │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
                          │
                          ▼
              ┌──────────────────────┐
              │    RAG 服务 (ct_rag) │
              │    向量检索 / 嵌入    │
              │    端口: 5050        │
              └──────────────────────┘
                          │
                          ▼
              ┌──────────────────────┐
              │   AI 大模型 API      │
              │   (OpenAI 兼容接口)   │
              └──────────────────────┘
```

---

## 外部依赖一览

| 依赖 | 用途 | 必须 | 默认地址/端口 |
|------|------|------|--------------|
| PostgreSQL | 主数据库 | 是 | panda-wiki-postgres:5432 |
| Redis | 缓存 + Session | 是 | panda-wiki-redis:6379 |
| NATS | 异步任务队列 | 是 | subnet.13:4222 |
| MinIO (S3) | 文件存储 | 是 | panda-wiki-minio:9000 |
| RAG 服务 | 文档向量化与语义搜索 | 是 | subnet.18:5050 |
| AI 模型 API | AI 创作/问答/搜索 | 推荐 | 用户自行配置 |
| Caddy | 反向代理/SSL | 推荐 | 自动管理 |

所有依赖均可通过 Docker Compose 一键启动。

---

## 构建与运行

### 环境要求

- Go 1.24+
- Node.js 20+ (推荐 22)
- pnpm 10+
- Docker 20.x+ (用于运行依赖服务)

### 第一步：启动依赖服务

创建 `docker-compose.yml`：

```yaml
version: '3.8'
services:
  postgres:
    image: postgres:16-alpine
    container_name: panda-wiki-postgres
    environment:
      POSTGRES_USER: panda-wiki
      POSTGRES_PASSWORD: panda-wiki-secret
      POSTGRES_DB: panda-wiki
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    container_name: panda-wiki-redis
    command: redis-server --appendonly yes
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  nats:
    image: nats:2-alpine
    container_name: panda-wiki-nats
    command: "-js -m 8222 --user panda-wiki --pass your-nats-password"
    ports:
      - "4222:4222"
      - "8222:8222"

  minio:
    image: minio/minio:latest
    container_name: panda-wiki-minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: s3panda-wiki
      MINIO_ROOT_PASSWORD: your-s3-secret-key
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data

volumes:
  pg_data:
  redis_data:
  minio_data:
```

```bash
docker compose up -d
```

### 第二步：配置后端

创建 `backend/config/config.yml`：

```yaml
http:
  port: 8000

pg:
  dsn: "host=localhost user=panda-wiki password=panda-wiki-secret dbname=panda-wiki port=5432 sslmode=disable TimeZone=Asia/Shanghai"

redis:
  addr: "localhost:6379"
  password: ""

mq:
  type: "nats"
  nats:
    server: "nats://localhost:4222"
    user: "panda-wiki"
    password: "your-nats-password"

rag:
  provider: "ct"
  ct_rag:
    base_url: "http://localhost:5050"
    api_key: "sk-1234567890"

auth:
  type: "jwt"
  jwt:
    secret: "your-jwt-secret-key-change-in-production"

s3:
  endpoint: "localhost:9000"
  access_key: "s3panda-wiki"
  secret_key: "your-s3-secret-key"

log:
  level: -4   # -4=debug, 0=info, 4=warn, 8=error

sentry:
  enabled: false
```

### 第三步：构建后端

```bash
# 进入后端目录
cd backend

# 下载依赖
go mod tidy

# 安装代码生成工具
go install github.com/google/wire/cmd/wire@latest
go install github.com/swaggo/swag/cmd/swag@latest

# 生成 wire 依赖注入代码 和 swagger 文档
make generate

# 编译
go build -o panda-wiki-api ./cmd/api/

# 运行数据库迁移
go run ./cmd/migrate/

# 启动 API 服务
./panda-wiki-api
```

### 第四步：构建前端

```bash
# 进入前端目录
cd web

# 安装依赖
pnpm install

# 生成 API 请求客户端代码 (从 swagger 文档)
pnpm --filter panda-wiki-admin api
pnpm --filter panda-wiki-app api

# 开发模式启动 (两个项目同时)
pnpm dev

# 或者分别构建
pnpm --filter panda-wiki-admin build
pnpm --filter panda-wiki-app build
```

### 第五步：访问

- 管理后台: http://localhost:5173
- 用户端 Wiki: http://localhost:3010
- API 服务: http://localhost:8000
- Swagger 文档: http://localhost:8000/swagger/ (设置 ENV=local)

---

## Docker 构建 (生产环境)

### 后端 Docker 镜像

```bash
cd backend

# 构建 API 镜像
docker build -f Dockerfile.api -t panda-wiki-api:latest .

# 构建 Consumer 镜像 (异步任务)
docker build -f Dockerfile.consumer -t panda-wiki-consumer:latest .
```

### 前端 Docker 镜像

```bash
cd web/admin
docker build -t panda-wiki-admin:latest .

cd web/app
docker build -t panda-wiki-app:latest .
```

---

## 注意事项

### 关于 Pro 功能

`backend/pro/` 目录在当前开源仓库中为空，以下功能**需要自行实现** Pro handler 才能使用：

| 功能 | 状态 | 说明 |
|------|------|------|
| 知识库数量无限制 | 已解锁 | 修改 `MaxKb` |
| 文档数量无限制 | 已解锁 | 修改 `MaxNode` |
| 管理员无限制 | 已解锁 | 修改 `MaxAdmin` |
| 管理员分权控制 | 已解锁 | `AllowAdminPerm: true` |
| 自定义版权信息 | 已解锁 | `AllowCustomCopyright: true` |
| 评论审核 | 已解锁 | `AllowCommentAudit: true` |
| 高级机器人配置 | 已解锁 | `AllowAdvancedBot: true` |
| 水印功能 | 已解锁 | `AllowWatermark: true` |
| 复制保护 | 已解锁 | `AllowCopyProtection: true` |
| MCP Server | 已解锁 | `AllowMCPServer: true` |
| 文档统计 | 已解锁 | `AllowNodeStats: true` |
| 全周期数据统计 | 已解锁 | 移除 ValidateStatDay 版本限制 |
| SSO 登录 (LDAP/CAS/OAuth) | 需自行开发 | Pro handler 代码缺失 |
| API Token 管理 | 需自行开发 | Pro handler 代码缺失 |
| 文档版本历史 | 需自行开发 | Pro handler 代码缺失 |
| 敏感词过滤 | 需自行开发 | Pro handler 代码缺失 |
| 文档反馈/贡献审核 | 需自行开发 | Pro handler 代码缺失 |

### Windows 开发注意事项

项目依赖 `bytedance/sonic` 库 (高性能 JSON 解析)，该库在 Windows 上编译会失败。解决方案：

1. **推荐**: 使用 WSL2 或 Linux 虚拟机进行后端开发
2. **替代**: 在 `go.mod` 中替换 sonic 为标准库 `encoding/json`（性能较低但兼容 Windows）
3. **只改前端**: 如果只修改前端代码，可以直接在 Windows 上 `pnpm dev`

```bash
# WSL2 方案
wsl --install
cd /mnt/e/code\ project/PandaWiki-3.85.0/backend
go build ./...
```

### 键环境变量

| 变量 | 说明 |
|------|------|
| `POSTGRES_PASSWORD` | 数据库密码 |
| `NATS_PASSWORD` | NATS 密码 |
| `REDIS_PASSWORD` | Redis 密码 |
| `JWT_SECRET` | JWT 签名密钥 |
| `S3_SECRET_KEY` | MinIO/S3 密钥 |
| `ADMIN_PASSWORD` | 管理员初始密码 |
| `ENV=local` | 启用 Swagger 文档和 Debug 模式 |
| `READONLY=1` | 只读模式 |

---

## 快速启动脚本 (开发模式)

将以下内容保存为 `start-dev.sh`：

```bash
#!/bin/bash
set -e

# 1. 启动依赖
echo "=== 启动 Docker 依赖 ==="
docker compose up -d postgres redis nats minio

# 2. 启动后端
echo "=== 启动后端 ==="
cd backend
go run ./cmd/migrate/
go run ./cmd/api/ &
BACKEND_PID=$!
cd ..

# 3. 启动前端
echo "=== 启动前端 ==="
cd web
pnpm dev &
FRONTEND_PID=$!
cd ..

echo "=== 启动完成 ==="
echo "后端:  http://localhost:8000"
echo "管理:  http://localhost:5173"
echo "Wiki:  http://localhost:3010"
echo "按 Ctrl+C 停止"

trap "kill $BACKEND_PID $FRONTEND_PID 2>/dev/null" EXIT
wait
```

---

## 版本信息

- 原始项目: PandaWiki 3.85.0 (chaitin/PandaWiki)
- 许可证: AGPL-3.0
- 修改日期: 2026-05-21