# openclaw-wiki

**Repository Path**: suxuss_admin/openclaw-wiki

## Basic Information

- **Project Name**: openclaw-wiki
- **Description**: 自演化现代wiki，完全由Openclaw多智能体协同演化
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wiki-backend

![Go Version](https://img.shields.io/github/go-mod/go-version/suxuss_admin/openclaw-wiki?filename=wiki-backend%2Fgo.mod)
![License](https://img.shields.io/github/license/suxuss_admin/openclaw-wiki)
![Build Status](https://img.shields.io/github/actions/workflow/status/suxuss_admin/openclaw-wiki/backend.yml?branch=master&label=build)

简洁高效的知识库后端服务，支持用户认证、知识空间管理、Markdown 文档编辑与分享。

## 技术栈

| 分类 | 技术 |
|------|------|
| 语言 | Go 1.22 |
| Web 框架 | Gin |
| ORM | GORM |
| 数据库 | PostgreSQL |
| 缓存 | Redis |
| 认证 | JWT (access token + refresh token) |
| 密码加密 | bcrypt |
| 配置管理 | godotenv |

## 功能特性

- **用户认证**：注册 / 登录 / 登出 / Token 刷新（HttpOnly Cookie + JSON 双通道）
- **知识空间**：创建、编辑、删除空间；支持公开/私有；成员角色管理（owner / admin / member / viewer）
- **文档管理**：创建、编辑、删除 Markdown 文档；文档版本历史；支持父子文档层级；软删除
- **文档分享**：生成加密链接（可选密码、可选过期时间、可选编辑权限）；分享链接访问计数
- **权限控制**：基于 Space 的 RBAC 权限体系；Jwt 中间件认证
- **数据库迁移**：支持顺序迁移与回滚（up / down）

## 快速开始

### 环境要求

- Go 1.22+
- PostgreSQL 15+
- Redis 7+
- Git

### 本地启动

**1. 配置环境变量**

在 `wiki-backend` 目录下创建 `.env` 文件：

```env
# 数据库
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=wiki
DB_SSLMODE=disable

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET=your-secret-key-change-in-production
JWT_ACCESS_TTL=15m
JWT_REFRESH_TTL=168h

# 服务
PORT=8080
GIN_MODE=debug
```

**2. 安装依赖**

```bash
go mod download
go mod tidy
```

**3. 运行数据库迁移**

```bash
go run ./cmd/server -migrate
```

**4. 启动服务**

```bash
go run ./cmd/server
```

服务将在 `http://localhost:8080` 启动。

> 注意：这里必须运行整个 `./cmd/server` 包，不能只运行 `./cmd/server/main.go`。
> 因为启动逻辑还依赖同目录下的 `migrate.go` 和 `initializers.go`；
> 若只执行单文件，会出现 `undefined: validateMigrations`、`undefined: initRedis` 等编译错误。

### Docker 启动（基础设施）

使用 `docker-compose.infra.yml` 启动 PostgreSQL 和 Redis：

```bash
docker-compose -f docker-compose.infra.yml up -d
```

### Docker 完整启动

使用项目根目录下的 `docker-compose.yml`（需配合 frontend 分支）启动全部服务：

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

### Make 命令

```bash
make deps          # 下载并整理依赖
make build        # 编译二进制到 bin/wiki-backend
make run          # 本地运行（等价于 go run ./cmd/server）
make migrate      # 执行数据库迁移
make migrate-down # 回滚上一次迁移
make test         # 运行测试
make clean        # 清理构建产物
make docker-build  # 构建 Docker 镜像
```

## 目录结构

```
wiki-backend/
├── cmd/
│   └── server/
│       └── main.go          # 应用入口
├── internal/
│   ├── handler/             # HTTP 处理器（Auth / Space / Doc / Share / Health）
│   ├── middleware/         # JWT 认证 / CORS / Cookie 中间件
│   ├── model/               # GORM 数据模型
│   ├── repository/          # 数据库操作
│   ├── service/             # 业务逻辑层
│   └── response/            # 统一 API 响应格式
├── migrations/              # SQL 迁移文件（up / down）
├── scripts/                 # 辅助脚本
├── docker-compose.yml       # 完整服务编排
├── docker-compose.infra.yml # 仅数据库基础设施
├── Makefile                # 构建命令
└── go.mod / go.sum
```

## API 概览

基础路径：`/api`

所有受保护接口（标注 🔒）需要在请求头中携带 `Authorization: Bearer <access_token>`。

### 认证接口

| 方法 | 路径 | 说明 | 鉴权 |
|------|------|------|------|
| POST | `/api/auth/register` | 用户注册 | 否 |
| POST | `/api/auth/login` | 用户登录（支持用户名或邮箱） | 否 |
| POST | `/api/auth/refresh` | 刷新 Token | 否 |
| POST | `/api/auth/logout` | 登出 | 🔒 |
| GET | `/api/auth/me` | 获取当前用户信息 | 🔒 |
| PUT | `/api/auth/me` | 更新个人资料（nickname/avatar） | 🔒 |
| PUT | `/api/auth/password` | 修改密码 | 🔒 |
| GET | `/api/users/search?q=xxx` | 用户搜索（用户名/昵称/邮箱） | 🔒 |

### 知识空间接口

| 方法 | 路径 | 说明 | 鉴权 |
|------|------|------|------|
| GET | `/api/spaces` | 获取空间列表（分页） | 🔒 |
| POST | `/api/spaces` | 创建空间 | 🔒 |
| GET | `/api/spaces/:id` | 获取空间详情 | 🔒 |
| PUT | `/api/spaces/:id` | 更新空间 | 🔒 |
| DELETE | `/api/spaces/:id` | 删除空间（仅所有者） | 🔒 |

### 文档接口

| 方法 | 路径 | 说明 | 鉴权 |
|------|------|------|------|
| GET | `/api/spaces/:spaceId/docs` | 获取空间内文档列表 | 🔒 |
| POST | `/api/spaces/:spaceId/docs` | 创建文档 | 🔒 |
| GET | `/api/docs/search` | 搜索文档（支持全局与空间内） | 🔒 |
| GET | `/api/docs/:id` | 获取文档详情（需 view+） | 🔒 |
| PUT | `/api/docs/:id` | 更新文档（需 edit+，自动保存版本） | 🔒 |
| DELETE | `/api/docs/:id` | 删除文档（需 admin，软删除） | 🔒 |

### 分享接口

| 方法 | 路径 | 说明 | 鉴权 |
|------|------|------|------|
| POST | `/api/docs/:id/shares` | 创建分享链接 | 🔒 |
| GET | `/api/docs/:id/shares` | 获取文档分享列表（需文档 view+） | 🔒 |
| GET | `/api/shares/:token` | 通过分享 Token 访问文档 | 否 |
| DELETE | `/api/shares/:token` | 删除分享链接 | 🔒 |

### 健康检查

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 服务健康状态 |

## 运行与验证

### 健康检查

```bash
curl -i http://localhost:8080/health
```

### 最小可用 curl 验证

```bash
# 1) 注册（已存在会返回 409，可忽略）
curl -s -X POST http://localhost:8080/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","email":"demo@example.com","password":"123456"}'

# 2) 登录（支持用户名或邮箱）并提取 Token
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","password":"123456"}' | \
  sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')

# 3) 调用受保护接口
curl -s http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer $TOKEN"
```

## CI 说明

后端 CI 工作流位置：

- `.github/workflows/ci.yml`

默认执行项包括：依赖下载、构建、`go vet`、`/health` 健康检查。

### API 统一响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

分页响应在 `data` 中包含 `items`, `total`, `page`, `page_size`, `has_more`。

### 错误码

| 区间 | 说明 |
|------|------|
| 0 | 成功 |
| 1001-1999 | 参数错误 |
| 2001-2999 | 认证/授权错误 |
| 3001-3999 | 资源错误（未找到/冲突） |
| 4001-4999 | 服务器内部错误 |

## 数据库表结构

| 表名 | 说明 |
|------|------|
| `users` | 用户（username, email, password, nickname, avatar, status） |
| `spaces` | 知识空间（name, description, owner_id, is_public, status） |
| `space_members` | 空间成员关联（space_id, user_id, role） |
| `docs` | 文档（title, content, summary, space_id, author_id, parent_id, version, status） |
| `doc_permissions` | 文档级权限（doc_id, user_id, role） |
| `doc_versions` | 文档版本历史 |
| `shares` | 分享记录（doc_id, share_token, password, expires_at, allow_edit, view_count） |
| `refresh_tokens` | Refresh Token 存储（token_hash, expires_at） |

## 环境变量配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DB_HOST` | `localhost` | PostgreSQL 主机 |
| `DB_PORT` | `5432` | PostgreSQL 端口 |
| `DB_USER` | `postgres` | 数据库用户 |
| `DB_PASSWORD` | `postgres` | 数据库密码 |
| `DB_NAME` | `wiki` | 数据库名 |
| `DB_SSLMODE` | `disable` | SSL 模式 |
| `REDIS_HOST` | `localhost` | Redis 主机 |
| `REDIS_PORT` | `6379` | Redis 端口 |
| `JWT_SECRET` | （必须设置） | JWT 签名密钥 |
| `JWT_ACCESS_TTL` | `15m` | Access Token 有效期 |
| `JWT_REFRESH_TTL` | `168h` | Refresh Token 有效期 |
| `PORT` | `8080` | HTTP 服务端口 |
| `GIN_MODE` | `debug` | Gin 运行模式（debug / release） |

## 贡献指南

1. Fork 本仓库并从 `master` 分支创建新分支
2. 代码风格遵循 Go 官方 `gofmt` 规范
3. 提交前运行 `make test` 确保通过
4. 提交 PR 并描述改动内容

## 许可证

本项目基于 [MIT License](LICENSE) 开源。