49 KiB

Raw Permalink Blame History

PandaWiki 项目说明书

📋 目录

项目概述
核心特性
技术架构
系统要求
安装部署
开发指南
API 文档
配置说明
安全策略
贡献指南
许可证
社区支持

项目概述

🎯 项目简介

PandaWiki 是一款由 AI 大模型驱动的开源知识库搭建系统，旨在帮助用户快速构建智能化的产品文档、技术文档、FAQ 和博客系统。通过集成先进的大语言模型技术，PandaWiki 为用户提供 AI 创作、AI 问答、AI 搜索 等智能化功能。

🏢 开发团队

开发组织: 长亭科技 (Chaitin Tech)
项目仓库: https://github.com/chaitin/PandaWiki
官方网站: https://ly.safepoint.cloud/Br48PoX
当前版本: v3.13.1

🎨 设计理念

PandaWiki 秉承"智能化、易用性、开放性"的设计理念：

智能化: 深度集成 AI 大模型，提供智能创作、问答和搜索能力
易用性: 提供直观的管理界面和丰富的富文本编辑功能
开放性: 支持多种第三方集成和数据导入方式
可扩展性: 模块化架构设计，支持灵活的功能扩展

核心特性

🤖 AI 驱动功能

AI 辅助创作

基于大语言模型的智能内容生成
支持多种创作模式和风格调整
实时内容优化和建议

AI 智能问答

基于知识库内容的智能问答系统
支持自然语言查询和上下文理解
多轮对话和问题澄清能力

AI 增强搜索

语义搜索和关键词搜索结合
智能内容推荐和相关性排序
支持模糊查询和同义词匹配

📝 内容管理功能

富文本编辑器

编辑器支持: 兼容 Markdown 和 HTML 格式
实时协作: 基于 Tiptap 的多人实时编辑
格式导出: 支持导出为 Word、PDF、Markdown 等多种格式
语法高亮: 内置代码语法高亮和数学公式支持
媒体支持: 图片、视频、音频等多媒体内容管理

内容组织

知识库管理: 支持多个独立知识库的创建和管理
分类体系: 灵活的文档分类和标签系统
版本控制: 文档版本历史和回滚功能
权限控制: 细粒度的访问权限管理

🔗 集成与扩展

第三方应用集成

网页挂件: 支持嵌入到其他网站作为挂件
聊天机器人: 集成钉钉、飞书、企业微信等平台
API 接口: 完整的 RESTful API 支持
Webhook: 支持事件通知和自动化集成

数据导入方式

网页导入: 根据 URL 直接导入网页内容
批量导入: 通过网站 Sitemap 批量导入
RSS 订阅: 自动同步 RSS 源内容
文件导入: 支持多种格式的离线文件导入
第三方平台: 支持从 Notion、语雀、Confluence 等平台导入

🎨 用户体验

界面设计

响应式设计: 支持桌面端和移动端访问
主题定制: 支持明暗主题切换和自定义样式
多语言支持: 国际化界面设计
无障碍访问: 符合 Web 无障碍标准

性能优化

缓存机制: 多层缓存提升访问速度
CDN 支持: 静态资源 CDN 加速
懒加载: 图片和内容的智能懒加载
搜索优化: 全文搜索和索引优化

技术架构

🏗️ 整体架构

PandaWiki 采用现代化的微服务架构设计，主要包含以下组件：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web App       │    │   Admin Panel   │    │   API Gateway   │
│   (Next.js)     │    │   (React+Vite)  │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Backend API   │    │   Consumer      │    │   RAG Service   │
│   (Go)          │    │   (Go)          │    │   (Python)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
┌─────────────────────────────────────────────────────────────────┐
│                        基础设施层                                │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│  │ PostgreSQL  │ │    Redis    │ │    MinIO    │ │    NATS     │ │
│  │   (数据库)   │ │   (缓存)    │ │  (对象存储)  │ │  (消息队列)  │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘

🔧 后端技术栈

核心框架

编程语言: Go 1.24.3
Web 框架: Echo v4.13.4
依赖注入: Google Wire v0.6.0
配置管理: Viper v1.20.1

数据存储

主数据库: PostgreSQL (通过 GORM v1.26.1)
缓存系统: Redis v9.11.0
对象存储: MinIO v7.0.91
消息队列: NATS v1.42.0

AI 与机器学习

模型集成: ModelKit v2.0.6
向量数据库: 自研 RAG 服务
多模型支持:
- OpenAI GPT 系列
- DeepSeek 模型
- Google Gemini
- Ollama 本地模型
Token 计算: tiktoken-go v0.1.7

第三方集成

企业通讯:
- 钉钉 SDK v2.0.83
- 飞书 SDK v3.4.20
- 企业微信 API
- Discord v0.29.0
内容平台:
- Notion API v1.13.3
- 语雀集成
- Confluence 集成
认证授权:
- JWT v5.3.0
- LDAP v3.4.11
- OAuth2 v0.30.0

监控与可观测性

链路追踪: OpenTelemetry
指标监控: 自定义指标收集
日志管理: 结构化日志记录
健康检查: 内置健康检查端点

🎨 前端技术栈

管理后台 (Admin Panel)

框架: React 19 + Vite 6.0.1
UI 组件库: Material-UI v6.2.0
状态管理: Redux Toolkit v2.5.0
路由: React Router DOM v7.0.2
富文本编辑: Tiptap v3.3.0
表单处理: React Hook Form v7.54.1
数据可视化: ECharts v5.6.0
拖拽功能: DnD Kit v6.3.1

用户前台 (Web App)

框架: Next.js 15.4.6 + React 19.1.1
UI 组件库: Material-UI v7.1.0
Markdown 渲染: react-markdown v10.1.0
代码高亮: highlight.js v11.11.1
数学公式: KaTeX v0.16.22
图表渲染: Mermaid v11.9.0
设备检测: react-device-detect v2.2.3

开发工具链

包管理器: pnpm 10.12.1
类型检查: TypeScript 5.8.3
代码规范: ESLint + Prettier
API 生成: cx-swagger-api v1.0.1
Git 钩子: Husky v9.1.7
代码格式化: lint-staged v16.1.5

🐳 容器化部署

Docker 配置

API 服务:
- 开发版: Dockerfile.api
- 生产版: Dockerfile.api.pro
消费者服务:
- 开发版: Dockerfile.consumer
- 生产版: Dockerfile.consumer.pro
前端应用:
- 管理后台: web/admin/Dockerfile
- 用户前台: web/app/Dockerfile

构建工具

后端构建: Makefile + Go modules
前端构建: Vite (Admin) + Next.js (App)
多阶段构建: 优化镜像大小和安全性
健康检查: 内置容器健康检查

系统要求

🖥️ 硬件要求

最低配置

CPU: 2 核心
内存: 4GB RAM
存储: 20GB 可用空间
网络: 稳定的互联网连接

生产环境配置

CPU: 8 核心或更多
内存: 16GB RAM 或更多
存储: 100GB+ SSD 存储
网络: 专用网络连接
负载均衡: 支持高可用部署

💻 软件要求

操作系统

Linux: Ubuntu 20.04+ / CentOS 8+ / Debian 11+
容器运行时: Docker 20.x 或更高版本
容器编排: Docker Compose (可选)

依赖服务

数据库: PostgreSQL 13+
缓存: Redis 6+
对象存储: MinIO 或兼容 S3 的存储服务
消息队列: NATS Server 2.8+

开发环境

Go: 1.24.3 或更高版本
Node.js: 18+ (推荐使用 nvm 管理)
pnpm: 10.12.1 或更高版本
Git: 2.30+ 版本

安装部署

🚀 快速安装

一键安装脚本

PandaWiki 提供了便捷的一键安装脚本，适用于大多数 Linux 系统：

# 使用 root 权限执行安装脚本
bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

安装过程说明：

脚本会自动检测系统环境
安装必要的依赖（Docker、Docker Compose 等）
下载并配置 PandaWiki 服务
初始化数据库和基础配置
启动所有必要的服务

安装完成后的信息

安装成功后，终端会显示以下信息：

SUCCESS  控制台信息:
SUCCESS    访问地址(内网): http://192.168.1.100:2443
SUCCESS    访问地址(外网): http://your-domain.com:2443
SUCCESS    用户名: admin
SUCCESS    密码: [随机生成的密码]

🔧 手动部署

环境准备

安装 Docker 和 Docker Compose:

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 安装 Docker Compose
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

mkdir -p /opt/pandawiki
cd /opt/pandawiki

配置文件设置

创建 docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: pandawiki
      POSTGRES_USER: pandawiki
      POSTGRES_PASSWORD: your_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin123
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"

  nats:
    image: nats:2.10-alpine
    ports:
      - "4222:4222"
      - "8222:8222"

  pandawiki-api:
    image: chaitin/pandawiki-api:latest
    environment:
      - DATABASE_URL=postgres://pandawiki:your_password@postgres:5432/pandawiki
      - REDIS_URL=redis://redis:6379
      - MINIO_ENDPOINT=minio:9000
      - NATS_URL=nats://nats:4222
    depends_on:
      - postgres
      - redis
      - minio
      - nats
    ports:
      - "8000:8000"

  pandawiki-consumer:
    image: chaitin/pandawiki-consumer:latest
    environment:
      - DATABASE_URL=postgres://pandawiki:your_password@postgres:5432/pandawiki
      - REDIS_URL=redis://redis:6379
      - MINIO_ENDPOINT=minio:9000
      - NATS_URL=nats://nats:4222
    depends_on:
      - postgres
      - redis
      - minio
      - nats

  pandawiki-admin:
    image: chaitin/pandawiki-admin:latest
    environment:
      - TARGET=http://pandawiki-api:8000
    depends_on:
      - pandawiki-api
    ports:
      - "3000:3000"

  pandawiki-app:
    image: chaitin/pandawiki-app:latest
    environment:
      - TARGET=http://pandawiki-api:8000
    depends_on:
      - pandawiki-api
    ports:
      - "3010:3010"

volumes:
  postgres_data:
  redis_data:
  minio_data:

启动服务:

docker-compose up -d

检查服务状态:

docker-compose ps
docker-compose logs -f pandawiki-api

🔐 初始配置

首次登录

访问管理后台: http://your-server:3000
使用默认账户登录:
- 用户名: admin
- 密码: 查看安装日志或重置密码

AI 模型配置

PandaWiki 的核心功能依赖 AI 大模型，首次使用需要配置模型：

登录管理后台
进入系统设置 > AI 模型配置
配置 Chat 模型:
- 选择模型提供商（OpenAI、百智云、DeepSeek 等）
- 填入 API Key 和相关配置
- 测试连接确保配置正确

推荐的模型配置：

百智云模型广场: 注册即可获得免费额度
OpenAI GPT-4: 功能最全面，需要 API Key
DeepSeek: 性价比高，支持中文优化
本地 Ollama: 私有化部署，无需网络

创建知识库

进入知识库管理
点击"创建知识库"
填写基本信息:
- 知识库名称
- 描述信息
- 访问权限设置
- 主题样式配置
保存并发布

🌐 域名和 SSL 配置

Nginx 反向代理配置

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;

    # 管理后台
    location /admin {
        proxy_pass http://localhost:3000;
        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;
    }

    # API 接口
    location /api {
        proxy_pass http://localhost: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;
    }

    # Wiki 前台
    location / {
        proxy_pass http://localhost:3010;
        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;
    }
}

开发指南

🛠️ 开发环境搭建

环境要求

确保你的开发环境满足以下要求：

Go: 1.24.3+
Node.js: 18+ (推荐使用 nvm)
pnpm: 10.12.1+
Docker: 20.x+ (用于本地服务)
Git: 2.30+

克隆项目

# 克隆项目
git clone https://github.com/chaitin/PandaWiki.git
cd PandaWiki

# 初始化子模块
git submodule update --init --recursive

后端开发环境

cd backend

安装 Go 依赖:

go mod download

启动依赖服务:

# 使用 Docker Compose 启动数据库等服务
docker-compose -f docker-compose.dev.yml up -d postgres redis minio nats

配置环境变量:

# 复制配置文件
cp config/config.example.yaml config/config.yaml

# 编辑配置文件，填入数据库连接等信息
vim config/config.yaml

运行数据库迁移:

make migrate-up

启动 API 服务:

make run-api

启动消费者服务:

make run-consumer

前端开发环境

管理后台开发

cd web/admin

安装依赖:

pnpm install

配置环境变量:

# 创建环境配置文件
cp .env.example .env.local

# 编辑配置文件
vim .env.local

示例 .env.local 配置：

# 后端服务地址
TARGET=http://localhost:8000

# 静态文件服务地址
STATIC_FILE_TARGET=http://localhost:2443

# 开发环境知识库ID
DEV_KB_ID=your_dev_kb_id

# Swagger 配置
SWAGGER_BASE_URL=http://localhost:8000
SWAGGER_AUTH_TOKEN=your_swagger_token

启动开发服务器:

pnpm dev

用户前台开发

cd web/app

安装依赖:

pnpm install

配置环境变量:

# 创建环境配置文件
cp .env.example .env.local

# 编辑配置文件
vim .env.local

启动开发服务器:

pnpm dev

📁 项目结构

后端结构

backend/
├── api/                    # API 路由定义
├── cmd/                    # 应用程序入口
├── config/                 # 配置文件和配置管理
├── consts/                 # 常量定义
├── docs/                   # API 文档 (Swagger)
├── domain/                 # 领域模型和接口定义
├── handler/                # HTTP 处理器
├── middleware/             # 中间件
├── migration/              # 数据库迁移文件
├── mq/                     # 消息队列相关
├── pkg/                    # 公共包和工具
├── repo/                   # 数据访问层
├── server/                 # 服务器配置
├── store/                  # 存储层抽象
├── usecase/                # 业务逻辑层
├── utils/                  # 工具函数
├── go.mod                  # Go 模块定义
├── go.sum                  # Go 依赖校验
└── Makefile               # 构建脚本

前端结构

web/
├── admin/                  # 管理后台
│   ├── src/
│   │   ├── components/     # 可复用组件
│   │   ├── pages/          # 页面组件
│   │   ├── store/          # Redux 状态管理
│   │   ├── themes/         # 主题配置
│   │   ├── constant/       # 常量定义
│   │   └── utils/          # 工具函数
│   ├── public/             # 静态资源
│   ├── package.json        # 依赖配置
│   └── vite.config.ts      # Vite 配置
└── app/                    # 用户前台
    ├── src/
    │   ├── components/     # 可复用组件
    │   ├── views/          # 页面视图
    │   ├── hooks/          # 自定义 Hooks
    │   ├── utils/          # 工具函数
    │   └── middleware/     # 中间件
    ├── public/             # 静态资源
    ├── package.json        # 依赖配置
    └── next.config.ts      # Next.js 配置

🔄 开发工作流

代码提交流程

创建功能分支:

git checkout -b feat/your-feature-name

开发和测试:

# 后端测试
cd backend
make test
make lint

# 前端测试
cd web/admin
pnpm test
pnpm lint

cd web/app
pnpm test
pnpm lint

提交代码:

git add .
git commit -m "feat: add new feature description"
git push origin feat/your-feature-name

创建 Pull Request:
- 确保 PR 有清晰的标题和描述
- 关联相关 Issue
- 遵循 PR 模板要求

代码规范

Go 代码规范

使用 gofmt 格式化代码
遵循 Effective Go 指南
保持函数简洁（<80 行）
添加必要的注释和文档

TypeScript 代码规范

使用 ESLint 检查代码质量
遵循标准 React 最佳实践
使用 Prettier 格式化代码
保持组件的单一职责原则

测试要求

后端测试

所有主要功能应有单元测试
测试覆盖率不应低于 80%
运行测试命令: make test

前端测试

重要组件应包含基本测试
关键交互逻辑应有测试覆盖
运行测试命令: pnpm test

🔧 常用开发命令

后端命令

# 构建项目
make build

# 运行 API 服务
make run-api

# 运行消费者服务
make run-consumer

# 运行测试
make test

# 代码检查
make lint

# 数据库迁移
make migrate-up
make migrate-down

# 生成 API 文档
make swagger

前端命令

# 管理后台
cd web/admin
pnpm dev          # 开发模式
pnpm build        # 构建生产版本
pnpm lint         # 代码检查
pnpm format       # 代码格式化
pnpm api          # 生成 API 类型定义

# 用户前台
cd web/app
pnpm dev          # 开发模式 (端口 3010)
pnpm build        # 构建生产版本
pnpm start        # 启动生产服务器
pnpm lint         # 代码检查
pnpm format       # 代码格式化

API 文档

📚 API 概览

PandaWiki 提供完整的 RESTful API，支持所有核心功能的编程访问。API 文档通过 Swagger 自动生成，提供交互式的接口测试环境。

API 基础信息

Base URL: http://your-domain.com/api
API 版本: v1
认证方式: JWT Token
数据格式: JSON
字符编码: UTF-8

访问 API 文档

Swagger UI: http://your-domain.com/api/swagger/index.html
OpenAPI 规范: http://your-domain.com/api/swagger/doc.json

🔐 认证授权

JWT Token 认证

所有需要认证的 API 请求都需要在 Header 中包含 JWT Token：

Authorization: Bearer <your-jwt-token>

获取 Token

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-01T00:00:00Z",
    "user": {
      "id": "user-id",
      "username": "admin",
      "email": "admin@example.com"
    }
  }
}

📖 核心 API 接口

知识库管理

获取知识库列表

GET /api/knowledge-bases
Authorization: Bearer <token>

创建知识库

POST /api/knowledge-bases
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "我的知识库",
  "description": "知识库描述",
  "is_public": true,
  "settings": {
    "theme": "default",
    "language": "zh-CN"
  }
}

更新知识库

PUT /api/knowledge-bases/{kb_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "更新后的名称",
  "description": "更新后的描述"
}

删除知识库

DELETE /api/knowledge-bases/{kb_id}
Authorization: Bearer <token>

文档管理

获取文档列表

GET /api/knowledge-bases/{kb_id}/nodes
Authorization: Bearer <token>

创建文档

POST /api/knowledge-bases/{kb_id}/nodes
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "文档标题",
  "content": "文档内容（Markdown 格式）",
  "parent_id": "parent-node-id",
  "tags": ["标签1", "标签2"]
}

更新文档

PUT /api/nodes/{node_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "更新后的标题",
  "content": "更新后的内容"
}

删除文档

DELETE /api/nodes/{node_id}
Authorization: Bearer <token>

AI 功能接口

AI 创作

POST /api/ai/create
Authorization: Bearer <token>
Content-Type: application/json

{
  "prompt": "请帮我写一篇关于 Go 语言的技术文档",
  "knowledge_base_id": "kb-id",
  "style": "technical",
  "length": "medium"
}

AI 问答

POST /api/ai/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "question": "如何在 Go 中处理错误？",
  "knowledge_base_id": "kb-id",
  "conversation_id": "conv-id"
}

AI 搜索

POST /api/ai/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "Go 语言并发编程",
  "knowledge_base_id": "kb-id",
  "limit": 10
}

文件管理

上传文件

POST /api/files/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary-data>
knowledge_base_id: kb-id

获取文件信息

GET /api/files/{file_id}
Authorization: Bearer <token>

删除文件

DELETE /api/files/{file_id}
Authorization: Bearer <token>

📊 响应格式

标准响应格式

所有 API 响应都遵循统一的格式：

{
  "code": 0,
  "message": "success",
  "data": {
    // 具体的响应数据
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

错误响应格式

{
  "code": 400,
  "message": "参数错误",
  "error": "详细错误信息",
  "timestamp": "2024-01-01T00:00:00Z"
}

常见状态码

状态码	说明
0	成功
400	请求参数错误
401	未授权访问
403	权限不足
404	资源不存在
500	服务器内部错误

🔄 分页和过滤

分页参数

GET /api/nodes?page=1&page_size=20&sort=created_at&order=desc

过滤参数

GET /api/nodes?title=关键词&tags=标签1,标签2&created_after=2024-01-01

分页响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}

配置说明

⚙️ 系统配置

配置文件结构

PandaWiki 使用 YAML 格式的配置文件，主要配置文件位于 backend/config/config.yaml：

# 服务器配置
server:
  host: "0.0.0.0"
  port: 8000
  mode: "production"  # development, production
  cors:
    enabled: true
    origins: ["*"]
    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]

# 数据库配置
database:
  driver: "postgres"
  host: "localhost"
  port: 5432
  name: "pandawiki"
  username: "pandawiki"
  password: "your_password"
  ssl_mode: "disable"
  max_open_conns: 100
  max_idle_conns: 10
  conn_max_lifetime: "1h"

# Redis 配置
redis:
  host: "localhost"
  port: 6379
  password: ""
  database: 0
  pool_size: 10
  min_idle_conns: 5

# 对象存储配置
storage:
  provider: "minio"  # minio, s3, local
  endpoint: "localhost:9000"
  access_key: "minioadmin"
  secret_key: "minioadmin123"
  bucket: "pandawiki"
  region: "us-east-1"
  use_ssl: false

# 消息队列配置
message_queue:
  provider: "nats"  # nats, redis
  url: "nats://localhost:4222"
  cluster_id: "pandawiki"
  client_id: "pandawiki-api"

# AI 模型配置
ai:
  default_provider: "openai"
  providers:
    openai:
      api_key: "your-openai-api-key"
      base_url: "https://api.openai.com/v1"
      model: "gpt-4"
      max_tokens: 4000
      temperature: 0.7
    
    deepseek:
      api_key: "your-deepseek-api-key"
      base_url: "https://api.deepseek.com/v1"
      model: "deepseek-chat"
      max_tokens: 4000
      temperature: 0.7

# 认证配置
auth:
  jwt:
    secret: "your-jwt-secret"
    expires_in: "24h"
    refresh_expires_in: "168h"
  
  ldap:
    enabled: false
    host: "ldap.example.com"
    port: 389
    bind_dn: "cn=admin,dc=example,dc=com"
    bind_password: "admin_password"
    search_base: "ou=users,dc=example,dc=com"
    search_filter: "(uid=%s)"

# 日志配置
logging:
  level: "info"  # debug, info, warn, error
  format: "json"  # json, text
  output: "stdout"  # stdout, file
  file_path: "/var/log/pandawiki/app.log"
  max_size: 100  # MB
  max_backups: 10
  max_age: 30  # days

# 监控配置
monitoring:
  enabled: true
  metrics:
    enabled: true
    path: "/metrics"
  
  tracing:
    enabled: true
    endpoint: "http://jaeger:14268/api/traces"
    service_name: "pandawiki-api"

# 安全配置
security:
  rate_limit:
    enabled: true
    requests_per_minute: 100
    burst: 200
  
  captcha:
    enabled: true
    provider: "recaptcha"  # recaptcha, hcaptcha
    site_key: "your-site-key"
    secret_key: "your-secret-key"

🌐 环境变量

核心环境变量

# 数据库连接
DATABASE_URL=postgres://user:password@host:port/dbname

# Redis 连接
REDIS_URL=redis://host:port/database

# 对象存储
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin123

# AI 模型
OPENAI_API_KEY=your-openai-api-key
DEEPSEEK_API_KEY=your-deepseek-api-key

# JWT 密钥
JWT_SECRET=your-jwt-secret

# 服务端口
SERVER_PORT=8000

前端环境变量

管理后台 (.env.local)

# 后端服务地址
TARGET=http://localhost:8000

# 静态文件服务地址
STATIC_FILE_TARGET=http://localhost:2443

# 开发环境知识库ID
DEV_KB_ID=your_dev_kb_id

# Swagger 配置
SWAGGER_BASE_URL=http://localhost:8000
SWAGGER_AUTH_TOKEN=your_swagger_token

用户前台 (.env.local)

# 后端服务地址
TARGET=http://localhost:8000

# 静态文件服务地址
STATIC_FILE_TARGET=http://localhost:2443

# 开发环境知识库ID
DEV_KB_ID=your_dev_kb_id

🔧 高级配置

负载均衡配置

upstream pandawiki_api {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
}

upstream pandawiki_admin {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

upstream pandawiki_app {
    server 127.0.0.1:3010;
    server 127.0.0.1:3011;
}

缓存配置

cache:
  # 内存缓存
  memory:
    enabled: true
    max_size: "100MB"
    ttl: "1h"
  
  # Redis 缓存
  redis:
    enabled: true
    key_prefix: "pandawiki:"
    default_ttl: "24h"
    
    # 缓存策略
    strategies:
      nodes: "1h"
      search_results: "30m"
      user_sessions: "24h"

搜索引擎配置

search:
  # 全文搜索
  full_text:
    enabled: true
    language: "chinese"
    min_word_length: 2
    max_results: 100
  
  # 向量搜索
  vector:
    enabled: true
    model: "text-embedding-ada-002"
    dimension: 1536
    similarity_threshold: 0.7

安全策略

🔒 安全概述

PandaWiki 高度重视系统安全，采用多层次的安全防护措施，确保用户数据和系统的安全性。

🛡️ 安全措施

认证与授权

多因素认证:
- JWT Token 认证
- LDAP 企业认证集成
- OAuth2 第三方登录
- 可选的双因素认证 (2FA)
权限控制:
- 基于角色的访问控制 (RBAC)
- 细粒度的资源权限管理
- 知识库级别的访问控制
- API 接口权限验证

数据安全

数据加密:
- 传输层 TLS/SSL 加密
- 敏感数据库字段加密存储
- 文件上传安全检查
- API 密钥安全存储
数据备份:
- 自动化数据库备份
- 文件存储备份策略
- 灾难恢复计划
- 数据完整性验证

网络安全

防护措施:
- 请求频率限制 (Rate Limiting)
- DDoS 攻击防护
- SQL 注入防护
- XSS 攻击防护
- CSRF 攻击防护
监控与审计:
- 访问日志记录
- 异常行为检测
- 安全事件告警
- 操作审计跟踪

🚨 漏洞报告

报告流程

我们鼓励安全研究人员和用户报告发现的安全漏洞：

私下报告: 通过 GitHub Security Advisory 提交漏洞
响应时间: 我们会在 3 个工作日内确认收到报告
修复计划: 在 7 天内提供详细的修复时间表
公开披露: 修复完成后发布安全公告并感谢报告者

报告内容

请在报告中包含以下信息：

漏洞的详细描述
重现步骤和概念验证
潜在的影响和风险评估
建议的修复方案（如有）

负责任的披露

请勿在漏洞修复前公开披露
避免访问或修改他人数据
不要进行破坏性测试
遵守当地法律法规

🔐 安全最佳实践

部署安全

服务器安全:
- 定期更新操作系统和依赖
- 配置防火墙规则
- 禁用不必要的服务
- 使用非 root 用户运行服务
容器安全:
- 使用最小化的基础镜像
- 定期扫描镜像漏洞
- 配置容器资源限制
- 实施容器网络隔离

配置安全

密钥管理:
- 使用强密码和复杂密钥
- 定期轮换 API 密钥
- 避免在代码中硬编码密钥
- 使用密钥管理服务
网络配置:
- 启用 HTTPS/TLS 加密
- 配置安全的 HTTP 头
- 限制跨域访问
- 使用 VPN 或专网访问

运维安全

监控告警:
- 设置安全事件告警
- 监控异常登录行为
- 跟踪 API 调用异常
- 定期安全审计
备份恢复:
- 定期测试备份恢复
- 加密备份数据
- 异地备份存储
- 制定应急响应计划

📋 安全检查清单

部署前检查

更新所有依赖到最新安全版本
配置强密码和密钥
启用 HTTPS/TLS 加密
配置防火墙规则
设置访问日志和监控
测试备份和恢复流程

运行时检查

定期检查安全日志
监控系统资源使用
验证用户权限配置
检查 API 调用异常
更新安全补丁
执行安全扫描

贡献指南

🤝 参与贡献

我们欢迎所有形式的贡献，包括但不限于：

🐛 Bug 报告和修复
✨ 新功能开发
📚 文档改进
🌐 国际化翻译
🎨 UI/UX 改进
🧪 测试用例编写

📋 贡献流程

1. 准备工作

Fork 项目: 在 GitHub 上 Fork PandaWiki 项目
克隆代码: 克隆你的 Fork 到本地

git clone https://github.com/your-username/PandaWiki.git
cd PandaWiki

配置上游仓库:

git remote add upstream https://github.com/chaitin/PandaWiki.git

2. 开发流程

同步最新代码:

git fetch upstream
git checkout main
git merge upstream/main

创建功能分支:

git checkout -b feat/your-feature-name

开发和测试:
- 编写代码并确保功能正常
- 添加或更新相关测试
- 确保代码符合项目规范
提交代码:

git add .
git commit -m "feat: add your feature description"

3. 提交 Pull Request

推送分支:

git push origin feat/your-feature-name

创建 PR:
- 在 GitHub 上创建 Pull Request
- 填写详细的 PR 描述
- 关联相关的 Issue
代码审查:
- 响应审查意见
- 根据反馈修改代码
- 确保 CI 检查通过

📝 代码规范

提交信息规范

我们使用 Conventional Commits 规范：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型说明:

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建或工具相关

示例:

feat(api): add user authentication endpoint

Add JWT-based authentication for user login and registration.
Includes password hashing and token validation.

Closes #123

Go 代码规范

格式化: 使用 gofmt 格式化代码
命名: 遵循 Go 命名约定
注释: 为公开的函数和类型添加注释
错误处理: 正确处理和传播错误
测试: 为新功能编写单元测试

示例：

// UserService provides user management functionality.
type UserService struct {
    repo UserRepository
}

// CreateUser creates a new user with the given information.
func (s *UserService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
    if err := req.Validate(); err != nil {
        return nil, fmt.Errorf("invalid request: %w", err)
    }
    
    user, err := s.repo.Create(ctx, req)
    if err != nil {
        return nil, fmt.Errorf("failed to create user: %w", err)
    }
    
    return user, nil
}

TypeScript 代码规范

ESLint: 使用 ESLint 检查代码质量
Prettier: 使用 Prettier 格式化代码
类型安全: 充分利用 TypeScript 类型系统
组件设计: 遵循 React 最佳实践
性能优化: 合理使用 memo、useMemo 等

示例：

interface UserCardProps {
  user: User;
  onEdit?: (user: User) => void;
  onDelete?: (userId: string) => void;
}

export const UserCard: React.FC<UserCardProps> = memo(({ 
  user, 
  onEdit, 
  onDelete 
}) => {
  const handleEdit = useCallback(() => {
    onEdit?.(user);
  }, [user, onEdit]);

  const handleDelete = useCallback(() => {
    onDelete?.(user.id);
  }, [user.id, onDelete]);

  return (
    <Card>
      <CardContent>
        <Typography variant="h6">{user.name}</Typography>
        <Typography variant="body2">{user.email}</Typography>
      </CardContent>
      <CardActions>
        <Button onClick={handleEdit}>编辑</Button>
        <Button onClick={handleDelete} color="error">删除</Button>
      </CardActions>
    </Card>
  );
});

🧪 测试要求

后端测试

单元测试: 覆盖核心业务逻辑
集成测试: 测试 API 端点
覆盖率: 保持 80% 以上的测试覆盖率

func TestUserService_CreateUser(t *testing.T) {
    tests := []struct {
        name    string
        req     CreateUserRequest
        want    *User
        wantErr bool
    }{
        {
            name: "valid user",
            req: CreateUserRequest{
                Name:     "John Doe",
                Email:    "john@example.com",
                Password: "password123",
            },
            want: &User{
                Name:  "John Doe",
                Email: "john@example.com",
            },
            wantErr: false,
        },
        // 更多测试用例...
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // 测试实现...
        })
    }
}

前端测试

组件测试: 测试组件渲染和交互
Hook 测试: 测试自定义 Hook
集成测试: 测试页面级功能

import { render, screen, fireEvent } from '@testing-library/react';
import { UserCard } from './UserCard';

describe('UserCard', () => {
  const mockUser = {
    id: '1',
    name: 'John Doe',
    email: 'john@example.com',
  };

  it('renders user information', () => {
    render(<UserCard user={mockUser} />);
    
    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText('john@example.com')).toBeInTheDocument();
  });

  it('calls onEdit when edit button is clicked', () => {
    const onEdit = jest.fn();
    render(<UserCard user={mockUser} onEdit={onEdit} />);
    
    fireEvent.click(screen.getByText('编辑'));
    expect(onEdit).toHaveBeenCalledWith(mockUser);
  });
});

📚 文档贡献

文档类型

API 文档: Swagger/OpenAPI 规范
用户文档: 使用指南和教程
开发文档: 技术文档和架构说明
README: 项目介绍和快速开始

文档规范

清晰简洁: 使用简单明了的语言
结构化: 合理的标题层级和目录
示例丰富: 提供代码示例和截图
及时更新: 与代码变更保持同步

🌐 国际化贡献

我们欢迎社区贡献多语言支持：

翻译文件: 位于 locales/ 目录
支持语言: 中文、英文、日文等
翻译规范: 保持术语一致性
文化适配: 考虑本地化需求

🎯 Issue 管理

报告 Bug

使用 Bug 报告模板，包含：

问题描述和重现步骤
期望行为和实际行为
环境信息（版本、操作系统等）
相关日志和截图

功能建议

使用功能建议模板，包含：

功能描述和使用场景
预期收益和影响
实现建议（可选）
相关参考资料

🏆 贡献者认可

我们重视每一位贡献者的努力：

贡献者列表: 在 README 中展示
发布说明: 在版本发布中致谢
社区活动: 邀请参与社区活动
技术交流: 提供技术交流机会

许可证

📄 许可证信息

PandaWiki 采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。

🔍 许可证详情

权利

根据 AGPL-3.0 许可证，您享有以下权利：

使用权: 可以自由使用本软件
修改权: 可以修改源代码以满足您的需求
分发权: 可以分发原始软件或修改后的版本
专利权: 获得贡献者的专利许可

义务

使用本软件时，您需要遵守以下义务：

开源义务:
- 分发软件时必须提供源代码
- 修改后的版本也必须采用相同许可证
- 必须保留原始的版权声明和许可证信息
网络服务义务:
- 如果您通过网络提供基于本软件的服务
- 必须向用户提供完整的源代码
- 包括您对软件所做的任何修改
通知义务:
- 在软件界面中显示适当的版权声明
- 告知用户他们可以获取源代码的方式

商业使用

AGPL-3.0 允许商业使用，但有特殊要求：

SaaS 服务: 如果您提供基于 PandaWiki 的 SaaS 服务，必须开源您的修改
内部使用: 企业内部使用不需要开源，但网络服务需要
分发软件: 分发包含 PandaWiki 的软件产品时必须开源

⚖️ 许可证对比

许可证类型	使用	修改	分发	商业使用	开源要求	网络服务开源
MIT	✅	✅	✅	✅	❌	❌
GPL-3.0	✅	✅	✅	✅	✅	❌
AGPL-3.0	✅	✅	✅	✅	✅	✅

📋 合规指南

开源合规

如果您需要开源您的修改：

源代码管理:
- 在公开的代码仓库中维护源代码
- 确保代码可以被用户访问和下载
- 提供构建和部署说明
许可证文件:
- 在项目根目录包含 LICENSE 文件
- 在每个源文件头部包含许可证声明
- 更新 COPYRIGHT 文件记录修改
变更记录:
- 记录您对原始软件的修改
- 在 CHANGELOG 中说明变更内容
- 标明修改的作者和时间

商业合规

对于商业使用场景：

内部部署: 企业内部使用无需开源
客户部署: 为客户部署需要提供源代码
SaaS 服务: 提供网络服务必须开源修改
软件分发: 分发软件产品必须开源

法律建议

我们建议：

咨询律师: 对于复杂的商业场景，请咨询专业律师
许可证审查: 定期审查您的许可证合规性
文档记录: 保留详细的使用和修改记录
社区沟通: 与社区保持开放的沟通

🤝 双重许可

对于有特殊需求的商业用户，我们可能提供双重许可选项：

AGPL-3.0: 免费使用，需要开源
商业许可: 付费使用，无需开源

如需商业许可，请联系：

邮箱: [商业许可联系邮箱]
官网: [商业许可页面]

📞 许可证咨询

如果您对许可证有任何疑问：

常见问题: 查看 [许可证 FAQ]
社区讨论: 在 GitHub Discussions 中提问
官方支持: 联系官方技术支持
法律咨询: 咨询专业的开源许可证律师

社区支持

🌟 社区概览

PandaWiki 拥有活跃的开源社区，我们致力于为用户和开发者提供全方位的支持和交流平台。

💬 交流渠道

官方渠道

GitHub Discussions:
- 地址: https://github.com/chaitin/PandaWiki/discussions
- 用途: 技术讨论、功能建议、使用经验分享
GitHub Issues:
- 地址: https://github.com/chaitin/PandaWiki/issues
- 用途: Bug 报告、功能请求、技术支持
官方网站:
- 地址: https://ly.safepoint.cloud/Br48PoX
- 内容: 产品介绍、文档、下载链接

中文社区

微信交流群:
- 扫描二维码加入: [微信群二维码]
- 群内讨论: 使用问题、技术交流、版本更新
QQ 交流群:
- 群号: [QQ群号]
- 适合: 实时技术讨论和问题解答

国际社区

Discord 服务器:
- 邀请链接: [Discord邀请链接]
- 频道: 技术支持、开发讨论、公告通知
Reddit 社区:
- 地址: r/PandaWiki
- 内容: 用户分享、技术讨论、新闻更新

📚 学习资源

官方文档

用户手册:
- 快速开始指南
- 功能使用教程
- 常见问题解答
- 最佳实践指南
开发者文档:
- API 参考文档
- 架构设计说明
- 插件开发指南
- 贡献者指南
部署指南:
- 安装部署教程
- 配置参数说明
- 运维最佳实践
- 故障排除指南

视频教程

官方教程:
- 产品介绍视频
- 功能演示视频
- 部署安装教程
- 高级配置指南
社区贡献:
- 用户使用经验分享
- 开发者技术分享
- 实际案例分析
- 问题解决方案

博客文章

技术博客:
- 架构设计思路
- 技术实现细节
- 性能优化经验
- 安全最佳实践
用户故事:
- 企业使用案例
- 个人项目分享
- 迁移经验总结
- 定制开发案例

🎯 获取帮助

技术支持

问题分类:
- 🐛 Bug 报告: 使用 GitHub Issues
- ❓ 使用问题: 使用 GitHub Discussions
- 💡 功能建议: 使用 GitHub Issues
- 🔧 技术讨论: 使用社区群组
响应时间:
- 紧急问题: 24 小时内响应
- 一般问题: 3 个工作日内响应
- 功能建议: 1 周内评估反馈
支持范围:
- 安装部署问题
- 功能使用指导
- 配置参数说明
- 故障排除协助

商业支持

企业服务:
- 专业技术支持
- 定制开发服务
- 培训和咨询
- SLA 保障服务
联系方式:
- 邮箱: [企业服务邮箱]
- 电话: [企业服务电话]
- 在线咨询: [企业服务网站]

🤝 参与社区

贡献方式

代码贡献:
- 修复 Bug
- 开发新功能
- 改进性能
- 重构代码
文档贡献:
- 完善文档
- 翻译内容
- 编写教程
- 制作视频
社区建设:
- 回答问题
- 分享经验
- 组织活动
- 推广项目

社区活动

定期活动:
- 月度技术分享会
- 季度开发者大会
- 年度用户大会
- 在线研讨会
特殊活动:
- 黑客马拉松
- 代码贡献竞赛
- 文档改进活动
- 社区建设奖励

🏆 社区荣誉

贡献者认可

贡献者徽章:
- 代码贡献者
- 文档贡献者
- 社区建设者
- 长期支持者
年度奖项:
- 最佳贡献者
- 最佳新人
- 最佳文档
- 最佳社区建设

企业合作

合作伙伴:
- 技术合作伙伴
- 解决方案合作伙伴
- 培训合作伙伴
- 生态合作伙伴
案例展示:
- 成功案例分享
- 最佳实践展示
- 技术创新案例
- 行业解决方案

📈 社区数据

项目统计

GitHub Stars: [实时数据]
Fork 数量: [实时数据]
贡献者数量: [实时数据]
Issue 解决率: [实时数据]

社区规模

微信群成员: [实时数据]
Discord 成员: [实时数据]
月活跃用户: [实时数据]
文档访问量: [实时数据]

📞 联系我们

官方联系

项目主页: https://github.com/chaitin/PandaWiki
官方网站: https://ly.safepoint.cloud/Br48PoX
技术支持: [技术支持邮箱]
商务合作: [商务合作邮箱]

社交媒体

微博: @PandaWiki
Twitter: @PandaWiki
LinkedIn: PandaWiki
YouTube: PandaWiki Channel

📊 附录

🔗 相关链接

项目仓库: https://github.com/chaitin/PandaWiki
官方网站: https://ly.safepoint.cloud/Br48PoX
在线文档: https://pandawiki.docs.baizhi.cloud
API 文档: [Swagger UI 地址]
发布页面: https://github.com/chaitin/PandaWiki/releases

📋 版本历史

版本	发布日期	主要更新
v3.13.1	2024-01-01	Bug 修复和性能优化
v3.12.1	2023-12-15	新增 AI 搜索功能
v3.12.0	2023-12-01	重构前端架构
v3.11.0	2023-11-15	新增多语言支持

🙏 致谢

感谢所有为 PandaWiki 项目做出贡献的开发者、用户和社区成员。特别感谢：

长亭科技团队的核心开发
社区贡献者的代码和文档贡献
用户反馈和建议
开源社区的支持和帮助

文档版本: v1.0
最后更新: 2024年1月1日
维护团队: PandaWiki 开发团队

本文档基于 PandaWiki v3.13.1 版本编写，如有疑问或建议，请通过 GitHub Issues 或社区群组联系我们。

49 KiB Raw Permalink Blame History Unescape Escape

PandaWiki 项目说明书

📋 目录

项目概述

🎯 项目简介

🏢 开发团队

🎨 设计理念

核心特性

🤖 AI 驱动功能

AI 辅助创作

AI 智能问答

AI 增强搜索

📝 内容管理功能

富文本编辑器

内容组织

🔗 集成与扩展

第三方应用集成

数据导入方式

🎨 用户体验

界面设计

性能优化

技术架构

🏗️ 整体架构

🔧 后端技术栈

核心框架

数据存储

AI 与机器学习

第三方集成

监控与可观测性

🎨 前端技术栈

管理后台 (Admin Panel)

用户前台 (Web App)

开发工具链

🐳 容器化部署

Docker 配置

构建工具

系统要求

🖥️ 硬件要求

最低配置

推荐配置

生产环境配置

💻 软件要求

操作系统

依赖服务

开发环境

安装部署

🚀 快速安装

一键安装脚本

安装完成后的信息

🔧 手动部署

环境准备

配置文件设置

🔐 初始配置

首次登录

AI 模型配置

创建知识库

🌐 域名和 SSL 配置

Nginx 反向代理配置

开发指南

🛠️ 开发环境搭建

环境要求

克隆项目

后端开发环境

前端开发环境

管理后台开发

用户前台开发

📁 项目结构

后端结构

前端结构

🔄 开发工作流

代码提交流程

代码规范

Go 代码规范

TypeScript 代码规范

测试要求

后端测试

前端测试

🔧 常用开发命令

后端命令

前端命令

49 KiB

Raw Permalink Blame History