astronAgent Complete Deployment Guide

This guide will help you start all components of the astronAgent project in the correct order, including authentication, knowledge base, and core services.

📋 Project Architecture Overview

The astronAgent project consists of the following three main components:

Casdoor - Identity authentication and single sign-on service (required component, provides SSO functionality)
RagFlow - Knowledge base and document retrieval service (optional component, deploy as needed)
astronAgent - Core business service cluster (required component)

🚀 Deployment Steps

Prerequisites

Agent System Requirements

CPU >= 2 Core
RAM >= 4 GiB
Disk >= 50 GB

RAGFlow Requirements

CPU >= 4 Core
RAM >= 16 GB
Disk >= 50 GB

Step 1: Start Casdoor Identity Authentication Service

Casdoor is an open-source identity and access management platform that provides support for multiple authentication protocols including OAuth 2.0, OIDC, and SAML.

To start the Casdoor service, run our docker-compose-with-auth.yaml file. Before running the installation commands, please ensure that Docker and Docker Compose are installed on your machine.

bash

# Navigate to astronAgent directory
cd docker/astronAgent

# Start Casdoor service
docker compose -f docker-compose-auth.yml up -d

Service Information:

Access Address: http://localhost:8000
Container Name: casdoor
Default Configuration: Production mode (GIN_MODE=release)

Step 2: Start RagFlow Knowledge Base Service (Optional)

RagFlow is an open-source RAG (Retrieval-Augmented Generation) engine that provides accurate question-answering services using deep document understanding technology.

To start the RagFlow service, run our docker-compose.yml file or docker-compose-macos.yml. Before running the installation commands, please ensure that Docker and Docker Compose are installed on your machine.

bash

# Navigate to RagFlow directory
cd docker/ragflow

# Add executable permissions to all sh files
chmod +x *.sh

# Start RagFlow service (including all dependencies)
docker compose up -d

Access Address:

RagFlow Web Interface: http://localhost:18080

Model Configuration Steps:

Click on your avatar to enter the Model Providers page, select Add Model, fill in the corresponding API address and API Key, and add both Chat model and Embedding model respectively.
In the upper right corner of the same page, click Set Default Models to set the Chat model and Embedding model added in the first step as defaults.

Important Configuration Notes:

Elasticsearch is used by default. To use opensearch or infinity, modify the DOC_ENGINE configuration in .env
GPU acceleration is supported, start with docker-compose-gpu.yml

Step 3: Integrate Casdoor and RagFlow Services Configuration (Configure as needed)

Before starting astronAgent services, configure the relevant connection information to integrate Casdoor and RagFlow.

bash

# Navigate to astronAgent directory
cd docker/astronAgent

# Copy environment variable configuration
cp .env.example .env

3.1 Configure Knowledge Base Service Connection (Optional)

Edit the docker/astronAgent/.env file to configure RagFlow connection information:

bash

# Navigate to astronAgent directory
cd docker/astronAgent

# Edit environment variable configuration
vim .env

Key Configuration Items:

env

# RAGFlow Configuration
RAGFLOW_BASE_URL=http://localhost:18080
RAGFLOW_API_TOKEN=ragflow-your-api-token-here
RAGFLOW_TIMEOUT=60
RAGFLOW_DEFAULT_GROUP=星辰知识库

Obtaining RagFlow API Token:

Visit RagFlow Web Interface: http://localhost:18080
Log in and click on your avatar to enter user settings
Click API to generate an API KEY
Update the generated API KEY to RAGFLOW_API_TOKEN in the .env file

3.2 Configure Casdoor Authentication Integration (Required)

Edit the docker/astronAgent/.env file to configure Casdoor connection information:

Key Configuration Items:

env

# Casdoor Configuration
CONSOLE_CASDOOR_URL=http://your-casdoor-server:8000
CONSOLE_CASDOOR_ID=your-casdoor-client-id
CONSOLE_CASDOOR_APP=your-casdoor-app-name
CONSOLE_CASDOOR_ORG=your-casdoor-org-name

Obtaining Casdoor Configuration Information:

Visit the Casdoor management console: http://localhost:8000
Log in with the default administrator account: admin / 123
Create Organization Go to the http://localhost:8000/organizations page, click "Add", fill in the organization name, save and exit.
Create Application and Bind Organization Go to the http://localhost:8000/applications page, click "Add".

When creating the application, fill in the following information:
- Name: Custom application name, e.g., agent
- Redirect URL: Set to the project's callback address. If the Nginx exposed port is 80, use http://your-local-ip/callback; if it's another port (e.g., 888), use http://your-local-ip:888/callback
- Organization: Select the organization name you just created
After saving the application, record the following information and map it to the project configuration items:

Casdoor Information Item	Example Value	Corresponding `.env` Configuration Item
Casdoor Service Address (URL)	`http://localhost:8000`	`CONSOLE_CASDOOR_URL=http://localhost:8000`
Client ID	`your-casdoor-client-id`	`CONSOLE_CASDOOR_ID=your-casdoor-client-id`
Application Name (Name)	`your-casdoor-app-name`	`CONSOLE_CASDOOR_APP=your-casdoor-app-name`
Organization Name (Organization)	`your-casdoor-org-name`	`CONSOLE_CASDOOR_ORG=your-casdoor-org-name`

Fill in the above configuration information into the project's environment variable file:

bash

# Navigate to astronAgent directory
cd docker/astronAgent

# Edit environment variable configuration
vim .env

Step 4: Start astronAgent Core Services (Required Deployment Step)

4.1 Configure iFLYTEK Open Platform APP_ID, API_KEY, and Related Information

For documentation, see: https://www.xfyun.cn/doc/platform/quickguide.html

After creating your application, you may need to purchase or claim API authorization service quotas for the corresponding capabilities:

Spark LLM API: https://xinghuo.xfyun.cn/sparkapi (For the LLM API, you'll need an additional SPARK_API_PASSWORD available on the page) (1、The text generation/optimization feature for instruction-based assistants requires Spark Ultra. It can be enabled at: https://console.xfyun.cn/services/bm4 2、The AI generation and AI code generation capabilities for workflow agents require Spark 3.5 Max and DeepSeek V3. Spark 3.5 Max: https://console.xfyun.cn/services/bm35 DeepSeek V3: https://maas.xfyun.cn/modelSquare)
Real-time Speech Recognition API: https://console.xfyun.cn/services/rta
Image Generation API: https://www.xfyun.cn/services/wtop
Talk Agent: https://www.xfyun.cn/services/VirtualHumans

Edit the docker/astronAgent/.env file and update the relevant environment variables:

env

PLATFORM_APP_ID=your-app-id
PLATFORM_API_KEY=your-api-key
PLATFORM_API_SECRET=your-api-secret

SPARK_API_PASSWORD=your-api-password
SPARK_RTASR_API_KEY=your-rtasr-api-key

# For configuring platform AI generation capabilities (compatible with OpenAI protocols), such as prompt optimization and one-sentence agent creation.
AI_ABILITY_CHAT_BASE_URL=your-model-url
AI_ABILITY_CHAT_MODEL=your-model-id
AI_ABILITY_CHAT_API_KEY=your-api-key

4.2 If You Want to Use Spark RAG Cloud Service, Configure as Follows (Optional)

Spark RAG cloud service provides two usage methods:

Method 1: Obtain from the Web Interface

Use the APP_ID and API_SECRET created on the iFLYTEK Open Platform
Directly obtain the Spark dataset ID from the web interface, see: xinghuo_rag_tool.html

Method 2: Using cURL Command Line

If you prefer using command-line tools, you can create a dataset with the following cURL command:

bash

# Create Spark RAG dataset
curl -X PUT 'https://chatdoc.xfyun.cn/openapi/v1/dataset/create' \
    -H "Accept: application/json" \
    -H "appId: your_app_id" \
    -H "timestamp: $(date +%s)" \
    -H "signature: $(echo -n "$(echo -n "your_app_id$(date +%s)" | md5sum | awk '{print $1}')" | openssl dgst -sha1 -hmac 'your_api_secret' -binary | base64)" \
    -F "name=我的数据集"

Notes:

Please replace your_app_id with your actual APP ID
Please replace your_api_secret with your actual API Secret

After obtaining the dataset ID, please update it in the docker/astronAgent/.env file:

env

XINGHUO_DATASET_ID=

4.3 Start astronAgent Services

Before starting, please configure some required environment variables and ensure nginx and minio ports are exposed

bash

# Navigate to astronAgent directory
cd docker/astronAgent

# Modify configuration as needed
vim .env

env

HOST_BASE_ADDRESS=http://localhost (astronAgent service host address)

To start astronAgent services, run our docker-compose.yaml file. Before running the installation commands, please ensure that Docker and Docker Compose are installed on your machine.

bash

# Navigate to astronAgent directory
cd docker/astronAgent

# Start all services
docker compose up -d

📊 Service Access Addresses

After startup, you can access the services at the following addresses:

Authentication Service

Casdoor Admin Interface: http://localhost:8000

Knowledge Base Service

RagFlow Web Interface: http://localhost:18080

AstronAgent Core Services

Console Frontend (nginx proxy): http://localhost/

📚 Additional Resources

🤝 Technical Support

If you encounter issues, please:

Check the log files of related services
Review the official documentation and troubleshooting guides
Submit an Issue on the project's GitHub repository
Contact the technical support team

Note: For first-time deployment, it is recommended to verify all functionalities in a test environment before deploying to production.