init push
This commit is contained in:
405
SELF_BUILD_GUIDE.md
Normal file
405
SELF_BUILD_GUIDE.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user