RAGFlow Manager

A comprehensive web-based management platform for RAGFlow systems, featuring user management, department organization, permission control, and seamless RAGFlow API integration.

中文文档 | Docker Deployment Guide

Features

🔐 User Management

User Registration: Support for username, password, name, email registration with department selection
Authentication: Complete login, logout, and password reset functionality
CAPTCHA Protection: All authentication endpoints protected with CAPTCHA
Multi-language Support: Chinese and English interface

👨‍💼 Admin Dashboard

User Management: Create, edit, delete user accounts
Department Management: Organize users into departments
Permission Control: Assign permissions by department, support multi-department access
System Settings: Configure application name, RAGFlow API endpoints, API keys
Registration Control: Enable or disable public user registration
Global Configuration: Application name and settings apply across all pages with intelligent caching

🤖 RAGFlow Integration

Seamless API Integration: Connect with RAGFlow systems
Session Management: Create, manage, and track conversation sessions
Email Notifications: Send conversation content via email
Permission Isolation: Different departments use separate RAGFlow API keys
Multi-user Support: Complete isolation between users and sessions

🔒 Security Features

JWT Authentication: Token-based user authentication
Password Encryption: bcrypt hashing for password storage
CAPTCHA Protection: Prevent brute-force attacks
Permission Middleware: Strict authorization checks
Multi-level Caching: Backend (5-min cache) + Frontend (session cache) to prevent database hammering

Tech Stack

Backend

Language: Go 1.21+
Web Framework: Gin
Database: SQLite with WAL mode
Authentication: JWT + bcrypt
Email: SMTP via gomail

Frontend

Core: Vanilla HTML/CSS/JavaScript
Routing: Custom SPA router
Internationalization: Built-in i18n support

Quick Start

Method 1: Docker Deployment (Recommended)

Prerequisites

Docker 19.03+
Docker Compose

Steps

Clone the repository

git clone https://github.com/yourusername/ragflow-manager.git
cd ragflow-manager

Configure environment

cd docker
cp .env.example .env
# Edit .env file with your settings
nano .env

Start the service

docker-compose up -d

Access the application

Open your browser and navigate to: http://localhost:8082

Default admin credentials:

Username: admin
Password: admin123

Supported Architectures

linux/amd64 (x86_64)
linux/arm64 (ARMv8)
linux/arm/v7 (ARMv7)
linux/386 (x86)

The latest tag automatically selects the correct architecture for your platform.

Docker Commands

# View logs
docker-compose logs -f

# Stop service
docker-compose down

# Restart service
docker-compose restart

# Update to latest image
docker-compose pull
docker-compose up -d

Method 2: Manual Installation

Prerequisites

Go 1.21 or higher
SQLite3
Modern web browser

Installation Steps

Clone the repository

git clone https://github.com/yourusername/ragflow-manager.git
cd ragflow-manager

Install dependencies

go mod download

Create configuration file

cp config.json.example config.json
# Edit config.json with your settings

Example config.json:

{
  "server": {
    "port": ":8082",
    "host": "localhost",
    "mode": "release"
  },
  "database": {
    "path": "./data/ragflow.db",
    "driver": "sqlite3"
  },
  "smtp": {
    "host": "smtp.example.com",
    "port": 465,
    "username": "noreply@example.com",
    "password": "your-password",
    "from": "noreply@example.com",
    "ssl": false
  },
  "ragflow": {
    "base_url": "http://localhost:9380",
    "api_key": "your-ragflow-api-key"
  },
  "app": {
    "name": "RAGFlow Manager",
    "version": "1.0.0",
    "allow_registration": true,
    "default_language": "zh",
    "jwt_secret": "change-this-secret-in-production",
    "captcha_expire": 300
  }
}

Build and run

# Development mode
go run main.go

# Or build binary
go build -o ragflow-manager
./ragflow-manager

Access the application

Open browser and navigate to: http://localhost:8082

Default admin credentials:

Username: admin
Password: admin123

⚠️ Important: Change the admin password immediately after first login!

Project Structure

ragflow-manager/
├── main.go                     # Application entry point
├── go.mod                      # Go module file
├── go.sum                      # Dependency checksums
├── config.yaml.example         # Configuration template
├── README.md                   # Chinese documentation
├── README_EN.md               # English documentation (this file)
├── internal/                   # Internal packages
│   ├── config/                # Configuration management
│   ├── database/              # Database operations
│   ├── handlers/              # HTTP handlers
│   │   ├── admin.go           # Admin endpoints
│   │   ├── auth.go            # Authentication
│   │   ├── ragflow.go         # RAGFlow integration
│   │   └── user.go            # User management
│   ├── models/                # Data models
│   ├── server/                # Server setup
│   └── utils/                 # Utility functions
├── frontend/                   # Frontend assets
│   ├── index.html             # Entry page
│   ├── login.html             # Login page
│   ├── register.html          # Registration page
│   ├── chat.html              # Chat interface
│   ├── admin.html             # Admin dashboard
│   ├── profile.html           # User profile
│   ├── common.js              # Shared JavaScript
│   ├── router.js              # Frontend routing
│   └── styles.css             # Styles
├── docker/                     # Docker deployment
│   ├── Dockerfile             # Multi-arch Dockerfile
│   ├── docker-compose.yml     # Compose configuration
│   ├── .env.example           # Environment variables
│   ├── build.sh               # Linux/Mac build script
│   ├── build.bat              # Windows build script
│   └── README.md              # Docker documentation
└── data/                       # Data directory
    └── ragflow.db             # SQLite database

API Documentation

Authentication Endpoints

POST /api/auth/login - User login
POST /api/auth/register - User registration
POST /api/auth/logout - User logout
GET /api/auth/captcha - Get CAPTCHA image
GET /api/auth/verify - Verify JWT token

User Endpoints

GET /api/user/profile - Get user profile
PUT /api/user/profile - Update user profile
POST /api/user/change-password - Change password

Admin Endpoints

GET /api/admin/users - List all users
POST /api/admin/users - Create user
PUT /api/admin/users/:id - Update user
DELETE /api/admin/users/:id - Delete user
GET /api/admin/departments - List departments
POST /api/admin/departments - Create department
PUT /api/admin/departments/:id - Update department
DELETE /api/admin/departments/:id - Delete department
GET /api/admin/settings - Get system settings
PUT /api/admin/settings - Update system settings

RAGFlow Endpoints

GET /api/ragflow/config - Get RAGFlow configuration
GET /api/ragflow/datasets - List datasets
GET /api/ragflow/assistants - List assistants
POST /api/ragflow/chat - Send chat message
POST /api/ragflow/session - Create chat session
GET /api/ragflow/sessions - List user sessions
DELETE /api/ragflow/session/:id - Delete session

Public Endpoints

GET /api/config - Get public configuration (app name, registration settings)

Database Schema

Main Tables

users: User account information
departments: Department/group organization
department_permissions: Department-level permissions
sessions: Chat session records
conversations: Individual message records
system_settings: Application-wide settings
user_permissions: User-specific permissions

Configuration

Environment Variables (Docker)

Variable	Description	Default
`SERVER_PORT`	HTTP server port	`:8082`
`SERVER_MODE`	Run mode (debug/release)	`release`
`DATABASE_PATH`	SQLite database path	`/app/data/ragflow.db`
`JWT_SECRET`	JWT signing secret	Required
`JWT_EXPIRE`	JWT expiration time	`24h`
`TZ`	Timezone	`Asia/Shanghai`

Configuration File (Manual Installation)

See config.yaml.example for all available options.

Building Multi-Architecture Docker Images

For Linux/Mac

# Build all architectures
./docker/build.sh multiarch

# Build and push to Docker Hub
DOCKER_USERNAME=yourusername DOCKER_PASSWORD=yourtoken VERSION=1.0.0 \
  ./docker/build.sh dockerhub

# Quick single-arch build for testing
./docker/build.sh single linux/amd64

For Windows

REM Build all architectures
docker\build.bat multiarch

REM Build specific architecture
docker\build.bat single linux/amd64

See Docker Deployment Guide for detailed instructions.

Security Best Practices

Change Default Credentials: Update admin password immediately after installation
Use Strong JWT Secret: Generate a secure random string for JWT_SECRET
```
openssl rand -base64 32
```
Enable HTTPS: Use a reverse proxy (Nginx, Traefik) with SSL/TLS certificates
Restrict Ports: Only expose necessary ports in production
Regular Updates: Keep dependencies and Docker images up to date
Database Backups: Regularly backup data/ragflow.db

Production Deployment

Using systemd (Linux)

Build the binary

go build -o ragflow-manager

Create systemd service

sudo nano /etc/systemd/system/ragflow-manager.service

[Unit]
Description=RAGFlow Manager
After=network.target

[Service]
Type=simple
User=ragflow
WorkingDirectory=/opt/ragflow-manager
ExecStart=/opt/ragflow-manager/ragflow-manager
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl enable ragflow-manager
sudo systemctl start ragflow-manager
sudo systemctl status ragflow-manager

Nginx Reverse Proxy

server {
    listen 80;
    server_name ragflow.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ragflow.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8082;
        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;
    }
}

Troubleshooting

Common Issues

1. Port Already in Use

# Check what's using the port
netstat -tuln | grep 8082
# Or change the port in config.yaml

2. Database Permission Denied

# Ensure data directory is writable
chmod 755 ./data
chown -R $USER:$USER ./data

3. Docker Build Fails

# Install QEMU for multi-arch builds
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify buildx
docker buildx ls

4. Email Not Sending

Verify SMTP credentials
Check firewall/network connectivity
Enable "Less secure app access" for Gmail (or use App Password)

Viewing Logs

Docker deployment:

docker-compose logs -f ragflow-manager

Manual installation:

tail -f server.log

Development

Running Tests

go test ./...

Adding New Features

Create handler in internal/handlers/
Define models in internal/models/
Register routes in internal/server/server.go
Add frontend pages/components in frontend/

Database Migrations

Database schema is defined in internal/database/database.go. The InitDatabase() function creates tables on first run.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the GPLv3 License - see the LICENSE file for details.

Support

Documentation: docs/
Issues: GitHub Issues
Docker Guide: docker/README.md

Acknowledgments

Note: This is a management platform for RAGFlow. You need a running RAGFlow instance to use the RAGFlow integration features.

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
docker		docker
frontend		frontend
internal		internal
.gitattributes		.gitattributes
LICENSE		LICENSE
README.md		README.md
buildall.bat		buildall.bat
buildall.sh		buildall.sh
config.json.example		config.json.example
go.mod		go.mod
go.sum		go.sum
main.go		main.go
readme_zh.md		readme_zh.md

Folders and files

Latest commit

History

Repository files navigation

RAGFlow Manager

Features

🔐 User Management

👨‍💼 Admin Dashboard

🤖 RAGFlow Integration

🔒 Security Features

Tech Stack

Backend

Frontend

Quick Start

Method 1: Docker Deployment (Recommended)

Prerequisites

Steps

Supported Architectures

Docker Commands

Method 2: Manual Installation

Prerequisites

Installation Steps

Project Structure

API Documentation

Authentication Endpoints

User Endpoints

Admin Endpoints

RAGFlow Endpoints

Public Endpoints

Database Schema

Main Tables

Configuration

Environment Variables (Docker)

Configuration File (Manual Installation)

Building Multi-Architecture Docker Images

For Linux/Mac

For Windows

Security Best Practices

Production Deployment

Using systemd (Linux)

Nginx Reverse Proxy

Troubleshooting

Common Issues

Viewing Logs

Development

Running Tests

Adding New Features

Database Migrations

Contributing

License

Support

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages