# PandaNote

**Repository Path**: yang-shunxiong/PandaNote

## Basic Information

- **Project Name**: PandaNote
- **Description**: PandaNode 是基于 PandaWiki 二次开发的轻量型个人博客与笔记系统。保留 AI 写作、语义搜索、智能问答与富文本编辑能力，剥离多用户与企业级冗余设计，专注个人知识沉淀与博客创作。

- **Primary Language**: Go
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PandaNote - 个人博客笔记系统

> **版权声明**  
> 本项目是基于 [PandaWiki](https://github.com/chaitin/PandaWiki) 的衍生作品（Derivative Work）  
> 原项目版权所有 © [长亭科技](https://github.com/chaitin)  
> 本项目遵循 AGPL-3.0 许可证开源

## 📖 项目简介

PandaNote 是基于 [PandaWiki](https://github.com/chaitin/PandaWiki) 进行二次开发的个人博客笔记系统。

本项目专注于个人使用场景，移除了企业级权限管理等复杂功能，打造一个轻量、专注的个人知识管理工具。

## 🎯 项目定位

- **目标用户**：个人用户
- **使用场景**：个人博客、笔记管理、知识库
- **开发性质**：个人项目，开源但不保证及时更新
- **代码规范**：以实用为主，不强求严格的企业级规范

## 🔄 与原项目的关系

### 基于项目
- **原项目**：[PandaWiki](https://github.com/chaitin/PandaWiki)
- **原项目协议**：AGPL-3.0
- **当前版本**：基于 PandaWiki 主分支 (克隆时间: 2025-12-11)

### 开源协议
本项目遵循原项目的 **AGPL-3.0** 许可证。这意味着：

✅ **允许**：
- 自由使用、修改和分发本软件
- 用于个人和商业用途

⚠️ **要求**：
- 必须以相同的 AGPL-3.0 许可证开源你的修改
- 如果通过网络提供服务，也必须开源你的代码
- 必须保留原作者的版权声明

📄 **声明**：
本项目是 PandaWiki 的衍生作品（derivative work），感谢 [长亭科技](https://github.com/chaitin) 团队的开源贡献。

## 🚀 主要改进方向

### 已移除功能
- [ ] 企业级多用户权限管理系统
- [ ] 复杂的组织架构功能
- [ ] 企业协作相关功能
- [ ] 多知识库管理（简化为单知识库）
- [ ] 贡献功能（已移除）

### 新增/优化功能
- [ ] 简化的用户体系（个人使用）
- [ ] 优化的个人博客展示界面
- [ ] 更轻量的部署方案
- [ ] 个人化的配置选项
- [ ] 针对个人使用的性能优化

### 保留功能
- ✅ AI 辅助创作
- ✅ AI 问答
- ✅ AI 搜索
- ✅ 富文本编辑器
- ✅ Markdown 支持
- ✅ 导入导出功能
- ✅ 多种格式支持（PDF、Word、Markdown）

## 🛠️ 技术栈

### 后端
- **语言**：Go
- **框架**：Fiber
- **数据库**：PostgreSQL
- **对象存储**：MinIO
- **AI 服务**：支持多种大模型

### 前端
- **框架**：Vue 3
- **构建工具**：Vite
- **UI 组件**：Element Plus
- **编辑器**：富文本编辑器

### 爬虫服务
- **语言**：Python
- **框架**：FastAPI

## 📦 快速开始

### 环境要求

#### 开发环境
- **Go**: 1.21+
- **Node.js**: 18+ (推荐使用 pnpm 作为包管理器)
- **Docker**: 20.x+ (用于运行依赖服务)
- **Docker Compose**: 2.x+

#### 生产环境
- **Docker**: 20.x+
- **Docker Compose**: 2.x+
- **服务器**: Linux 系统，建议 2 核 4GB 内存以上

---

## 🛠️ 本地开发调试

> 详细的开发调试流程请参考 [`test/README.md`](test/README.md)

### 快速启动步骤

#### 1. 克隆项目
```bash
git clone https://gitee.com/yang-shunxiong/PandaNote
cd PandaNote
```

#### 2. 启动依赖服务
使用 Docker Compose 启动所有依赖服务（PostgreSQL、Redis、MinIO、NATS、Qdrant、Crawler、RAGLite）：

```bash
cd test
docker compose up -d
```

服务启动后，你可以访问：
- **PostgreSQL**: `localhost:54321` (用户名: `panda-note`, 密码: `panda-note-pass`)
- **Redis**: `localhost:6379` (密码: `panda-note-pass`)
- **MinIO Console**: `http://localhost:9001` (访问密钥: `s3panda-note`, 密钥: `panda-note-pass`)
- **Crawler Service**: `http://localhost:8080`
- **RAGLite Service**: `http://localhost:8081`

#### 3. 启动后端 API
```bash
cd test
./backend-start.sh
```

后端服务将在 `http://localhost:8000` 启动，包含：
- API 服务（端口 8000）
- Consumer 服务（后台异步任务处理）

#### 4. 启动前端

**启动管理后台（Admin）：**
```bash
cd web/admin
pnpm install  # 首次运行需要安装依赖
pnpm run dev
```
管理后台将在 `http://localhost:5173` 启动

**启动用户前台（App）：**
```bash
cd web/app
pnpm install  # 首次运行需要安装依赖
pnpm run dev
```
用户前台将在 `http://localhost:3010` 启动

#### 5. 访问应用
- **管理后台**: http://localhost:5173
- **用户前台**: http://localhost:3010
- **后端 API**: http://localhost:8000

---

## 🚀 生产环境部署

### 部署架构

生产环境包含以下组件：
- **前端 App 镜像**: 用户访问的 Wiki 网站
- **后端 API 镜像**: API 服务 + 管理后台静态文件
- **依赖服务**: PostgreSQL、Redis、MinIO、NATS、Qdrant、Crawler、RAGLite

### 部署步骤

#### 1. 构建前端 App 镜像

```bash
cd web/app

# 方式一：使用 Makefile（推荐）
make image

# 方式二：手动构建
pnpm run build
docker buildx build \
  -f Dockerfile \
  --platform linux/amd64 \
  --tag panda-note-app:main \
  --load \
  .
```

构建完成后，镜像名称为 `panda-note-app:main`

#### 2. 构建后端 API 镜像（自动包含 Admin 管理后台）

后端镜像会自动构建并包含 Admin 管理后台的静态文件，无需单独构建 Admin。

**方式一：使用一键构建脚本（最简单）**

```bash
# 在项目根目录执行
./build-backend.sh

# 或指定版本标签
./build-backend.sh v1.0.0
```

**方式二：使用 Makefile**

```bash
cd backend

# 快速构建（本地开发）
make build

# 或指定版本
make build TAG=v1.0.0
```

**方式三：手动构建**

```bash
cd backend

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

# 构建镜像
docker buildx build \
  -f Dockerfile.api \
  --platform linux/amd64 \
  --tag panda-note-api:main \
  --build-arg VERSION=main \
  --context .. \
  --load \
  .
```

构建完成后，镜像名称为 `panda-note-api:main`

> **📝 说明**：
> - 构建过程会自动编译 Admin 前端并将其打包到镜像中
> - Admin 静态文件位于镜像的 `/app/static/admin` 目录
> - 通过 `/admin` 路径即可访问管理后台
> - 构建时间约 5-10 分钟（首次构建会更长）

#### 3. 部署依赖服务

使用 Docker Compose 部署所有依赖服务：

```bash
cd test

# 启动所有依赖服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看服务日志
docker compose logs -f
```

#### 4. 部署应用服务

在 `docker-compose.yml` 中添加或取消注释 app 和 api 服务配置：

```yaml
services:
  # ... 其他依赖服务 ...

  app:
    container_name: panda-note-app
    restart: always
    image: panda-note-app:main
    environment:
      - TARGET=http://169.254.15.2:8000  # 后端 API 地址
    networks:
      panda-note:
        ipv4_address: "169.254.15.112"
    ports:
      - "3010:3010"

  api:
    container_name: panda-note-api
    depends_on:
      - postgres
      - nats
      - raglite
    restart: always
    image: panda-note-api:main
    environment:
      - NATS_PASSWORD=panda-note-pass
      - POSTGRES_PASSWORD=panda-note-pass
      - REDIS_PASSWORD=panda-note-pass
      - S3_SECRET_KEY=panda-note-pass
      - JWT_SECRET=your-jwt-secret-here
      - ADMIN_PASSWORD=your-admin-password
    networks:
      panda-note:
        ipv4_address: "169.254.15.2"
    ports:
      - "8000:8000"
```

然后启动应用服务：

```bash
docker compose up -d app api
```

#### 5. 验证部署

```bash
# 检查所有容器状态
docker compose ps

# 查看 API 日志
docker logs -f panda-note-api

# 查看 App 日志
docker logs -f panda-note-app

# 测试 API 健康状态
curl http://localhost:8000/health

# 测试前端访问
curl http://localhost:3010
```

#### 6. 访问应用

- **用户前台**: http://your-server-ip:3010
- **管理后台**: http://your-server-ip:8000/admin
- **API 文档**: http://your-server-ip:8000/swagger/index.html

### 环境变量配置

#### 后端 API 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `POSTGRES_PASSWORD` | PostgreSQL 数据库密码 | `panda-note-pass` |
| `REDIS_PASSWORD` | Redis 密码 | `panda-note-pass` |
| `S3_SECRET_KEY` | MinIO 密钥 | `panda-note-pass` |
| `NATS_PASSWORD` | NATS 密码 | `panda-note-pass` |
| `JWT_SECRET` | JWT 签名密钥 | 需要设置 |
| `ADMIN_PASSWORD` | 管理员初始密码 | 需要设置 |

#### 前端 App 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `TARGET` | 后端 API 地址 | `http://192.168.79.128:8000` |
| `PORT` | 应用监听端口 | `3010` |
| `HOSTNAME` | 监听地址 | `0.0.0.0` |

### 数据持久化

所有数据将持久化到 `test/deploy/data/` 目录：

```
test/deploy/data/
├── postgres/     # PostgreSQL 数据
├── redis/        # Redis 数据
├── minio/        # MinIO 对象存储
├── nats/         # NATS 消息队列
├── qdrant/       # Qdrant 向量数据库
└── raglite/      # RAGLite 数据
```

### 备份与恢复

#### 备份数据
```bash
cd test
tar -czf panda-note-backup-$(date +%Y%m%d).tar.gz deploy/data/
```

#### 恢复数据
```bash
cd test
tar -xzf panda-note-backup-YYYYMMDD.tar.gz
docker compose restart
```

---

## 📝 配置说明

详细配置说明请参考：
- 后端配置: `backend/config/config.go`
- 前端配置: `web/app/.env`
- Docker 配置: `test/docker-compose.yml`

## 📁 项目结构

```
PandaNote/
├── backend/          # Go 后端服务
│   ├── config/       # 配置管理
│   ├── handler/      # HTTP 处理器
│   ├── model/        # 数据模型
│   ├── pkg/          # 工具包
│   └── main.go       # 入口文件
├── web/              # 前端项目
│   └── app/          # Vue 应用
├── sdk/              # SDK 和工具
│   └── rag/          # 爬虫服务
├── docs/             # 项目文档
└── README.md         # 项目说明
```

详细结构请参考原项目的 `PROJECT_STRUCTURE.md`

## 🗺️ 开发路线图

### Phase 1: 项目初始化 ✅
- [x] 克隆原项目
- [x] 创建项目文档
- [ ] 配置 Git 远程仓库
- [ ] 创建开发分支策略

### Phase 2: 功能精简
- [ ] 移除企业级权限管理
- [ ] 简化用户体系
- [ ] 移除多知识库功能
- [ ] 清理不必要的依赖

### Phase 3: 个人化改造
- [ ] 优化个人博客界面
- [ ] 简化配置流程
- [ ] 添加个人化设置
- [ ] 优化部署方案

### Phase 4: 功能增强
- [ ] 改进编辑体验
- [ ] 优化 AI 功能
- [ ] 添加主题系统
- [ ] 性能优化

## 📝 开发指南

### 二次开发流程

1. **阅读原项目文档**
   - 了解 PandaWiki 的架构设计
   - 熟悉核心功能实现
   - 查看 `PROJECT_STRUCTURE.md`

2. **本地开发环境搭建**
   - 安装必要的开发工具
   - 配置数据库和中间件
   - 启动开发服务器

3. **功能改造**
   - 创建功能分支
   - 小步提交，便于回滚
   - 充分测试后合并

4. **文档更新**
   - 记录重要的修改
   - 更新相关文档
   - 添加必要的注释

### 分支策略

- `main` - 主分支，保持稳定
- `develop` - 开发分支
- `feature/*` - 功能分支
- `fix/*` - 修复分支

### 提交规范（建议）

虽然不强制要求，但建议遵循简单的提交规范：

```
feat: 添加新功能
fix: 修复问题
docs: 文档更新
refactor: 代码重构
style: 代码格式调整
chore: 构建/工具变动
```

## ⚠️ 重要说明

### 关于更新
- 本项目是个人项目，**不保证及时更新**
- 可能会落后于原项目 PandaWiki 的版本
- 如需最新功能，请参考原项目

### 关于代码质量
- 以实用为主，不追求完美
- 代码规范以可读性为基础
- 欢迎提出改进建议，但不保证采纳

### 关于支持
- 本项目主要服务于个人使用
- Issue 和 PR 会在有时间时处理
- 不提供商业级别的技术支持

## 🤝 贡献

虽然这是个人项目，但仍然欢迎：
- 提交 Bug 报告
- 提出功能建议
- 提交 Pull Request
- 完善文档

请注意：PR 可能需要较长时间审核。

## 📄 许可证

本项目采用 **AGPL-3.0** 许可证，继承自原项目 PandaWiki。

详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- 感谢 [长亭科技](https://github.com/chaitin) 开源 PandaWiki 项目
- 感谢所有为 PandaWiki 做出贡献的开发者
- 感谢开源社区的支持

## 📮 联系方式

- **项目主页**：[PandaNote](https://gitee.com/yang-shunxiong/PandaNote)
- **原项目**：https://github.com/chaitin/PandaWiki
- **问题反馈**：通过 GitHub Issues

---

**最后更新时间**：2025-12-11
**基于 PandaWiki 版本**：main branch (2025-12-11)