Recommended Deployment Guide

This guide provides multiple deployment methods, including traditional server deployment, aaPanel deployment, Docker Compose deployment, and detailed cloud storage configuration instructions.

Prerequisites
Method 1: Traditional Server Deployment
Method 2: aaPanel Deployment
Method 3: Docker Compose Deployment
Database Import Methods
Tencent Cloud Configuration Guide
Alibaba Cloud OSS Configuration
Huawei OBS Configuration
Other Cloud Storage Configurations

Prerequisites

Environment Requirements

Component	Version Requirement	Description
JDK	21+	Backend runtime environment
Node.js	18+	Frontend build environment
MySQL	5.7+/8.0	Database service
Nginx	1.20+	Reverse proxy (recommended)
Maven	3.8+	Backend build (or use Wrapper)

Server Requirements

Minimum: 2 cores, 4GB RAM, 50GB storage
Recommended: 4 cores, 8GB RAM, 100GB storage
OS: Ubuntu 20.04+/CentOS 7+/Debian 11+

Method 1: Traditional Server Deployment

1. Build Frontend and Backend

Backend Build

bash

# Enter backend directory
cd backend

# Build with Maven Wrapper (recommended)
./mvnw clean package -DskipTests

# Or use system Maven
mvn clean package -DskipTests

# After build, jar file is in target/ directory
ls target/*.jar
# Output: target/backend-0.0.1-SNAPSHOT.jar

Frontend Build

bash

# Enter frontend directory
cd frontend

# Install dependencies
npm install

# Production build
npm run build

# After build, static files are in dist/ directory
ls dist/

2. Server Deployment Steps

2.1 Upload Files to Server

bash

# Create application directory
mkdir -p /opt/astrnest
mkdir -p /opt/astrnest/storage/upload

# Upload backend jar
scp target/backend-0.0.1-SNAPSHOT.jar root@your-server:/opt/astrnest/

# Upload frontend static files
scp -r dist/* root@your-server:/opt/astrnest/frontend/

# Upload database initialization script
scp backend/db/init.sql root@your-server:/opt/astrnest/

2.2 Configure systemd Service

Create backend service file /etc/systemd/system/astrnest-backend.service:

ini

[Unit]
Description=AstrNest Backend Service
After=network.target mysql.service

[Service]
Type=simple
User=astrnest
WorkingDirectory=/opt/astrnest
Environment="SPRING_PROFILES_ACTIVE=prod"
Environment="ASTRNEST_DB_URL=jdbc:mysql://localhost:3306/astrnest?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai"
Environment="ASTRNEST_DB_USERNAME=astrnest"
Environment="ASTRNEST_DB_PASSWORD=your_db_password"
Environment="ASTRNEST_STORAGE_ROOT=/opt/astrnest/storage/upload"
Environment="ASTRNEST_STORAGE_PUBLIC=/upload"
Environment="ASTRNEST_ADMIN_PASSWORD=your_admin_password"
ExecStart=/usr/bin/java -jar /opt/astrnest/backend-0.0.1-SNAPSHOT.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Start service:

bash

# Reload systemd
systemctl daemon-reload

# Start backend service
systemctl start astrnest-backend

# Enable auto-start
systemctl enable astrnest-backend

# Check status
systemctl status astrnest-backend

2.3 Nginx Configuration

nginx

server {
    listen 80;
    server_name your-domain.com;
    
    # Frontend static files
    location / {
        root /opt/astrnest/frontend;
        try_files $uri $uri/ /index.html;
        index index.html;
    }
    
    # Backend API
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
    
    # Upload file access
    location /upload/ {
        alias /opt/astrnest/storage/upload/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
    
    # Swagger API docs
    location /swagger-ui/ {
        proxy_pass http://127.0.0.1:8080/swagger-ui/;
    }
    
    # WebSocket support (if needed)
    location /ws/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable configuration:

bash

ln -s /etc/nginx/sites-available/astrnest /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Method 2: aaPanel Deployment

1. Install aaPanel

bash

# CentOS
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec

# Ubuntu/Debian
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed8484bec

2. Install Required Software

Install in aaPanel:

Nginx 1.20+
MySQL 8.0
Java Project Manager (install JDK 21)

3. Create Website

Login to aaPanel
Click "Website" → "Add Site"
Enter domain, select PHP version as "Static"
Create database (record database name, username, password)

4. Deploy Backend

Method 1: Using Java Project Manager

Install Java Project Manager plugin
Click "Java Project" → "Add Project"
Select project type "Spring Boot"
Fill project info:
- Project path: /www/wwwroot/astrnest/backend
- Start file: backend-0.0.1-SNAPSHOT.jar
- Port: 8080
- JDK version: 21

Method 2: Manual Deployment

bash

# Upload jar to /www/wwwroot/astrnest/backend/

# Create start script /www/wwwroot/astrnest/start.sh
#!/bin/bash
export ASTRNEST_DB_URL="jdbc:mysql://localhost:3306/astrnest?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai"
export ASTRNEST_DB_USERNAME="your_db_user"
export ASTRNEST_DB_PASSWORD="your_db_password"
export ASTRNEST_STORAGE_ROOT="/www/wwwroot/astrnest/storage/upload"
cd /www/wwwroot/astrnest/backend
nohup java -jar backend-0.0.1-SNAPSHOT.jar > ../logs/app.log 2>&1 &

5. Deploy Frontend

bash

# Build frontend locally
cd frontend
npm install
npm run build

# Upload dist content to aaPanel
# Target path: /www/wwwroot/your-domain.com/

6. Configure Reverse Proxy

In aaPanel:

Click Website → Settings → Reverse Proxy
Add reverse proxy:
- Proxy name: backend
- Target URL: http://127.0.0.1:8080
- Send domain: $host

7. Configure Rewrite

nginx

location / {
    try_files $uri $uri/ /index.html;
}

location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

location /upload/ {
    alias /www/wwwroot/astrnest/storage/upload/;
    expires 30d;
}

Method 3: Docker Compose Deployment

1. Prepare Environment File

Create .env file:

bash

cp .env.example .env

Edit .env:

bash

# Database configuration
MYSQL_ROOT_PASSWORD=your_root_password
MYSQL_DATABASE=astrnest
MYSQL_USER=astrnest
MYSQL_PASSWORD=your_db_password

# Backend configuration
ASTRNEST_DB_URL=jdbc:mysql://mysql:3306/astrnest?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
ASTRNEST_DB_USERNAME=astrnest
ASTRNEST_DB_PASSWORD=your_db_password
ASTRNEST_STORAGE_ROOT=/storage/upload
ASTRNEST_STORAGE_PUBLIC=/upload
ASTRNEST_ADMIN_PASSWORD=your_admin_password

# Site configuration
PUBLIC_SITE_URL=https://your-domain.com
VITE_API_BASE_URL=http://backend:8080

2. Start Services

bash

docker compose --env-file .env up -d

3. View Logs

bash

# All services logs
docker compose logs -f

# Backend logs
docker compose logs -f backend

# Database logs
docker compose logs -f mysql

Database Import Methods

Linux/macOS

bash

mysql -u root -p < backend/db/init.sql

Windows

Use init_windows.sql (removed DELIMITER syntax, compatible with Navicat):

bash

mysql -u root -p < backend/db/init_windows.sql

Manual Import (Navicat)

Connect to MySQL with root account
Create database astrnest (charset utf8mb4)
Right-click database → Run SQL File → Select init_windows.sql

Common Permission Issues

If error Access denied for user 'astrnest'@'localhost':

sql

-- Execute with root
CREATE DATABASE IF NOT EXISTS astrnest CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

CREATE USER IF NOT EXISTS 'astrnest'@'localhost' IDENTIFIED BY 'your_password';
CREATE USER IF NOT EXISTS 'astrnest'@'%' IDENTIFIED BY 'your_password';

GRANT ALL PRIVILEGES ON astrnest.* TO 'astrnest'@'localhost';
GRANT ALL PRIVILEGES ON astrnest.* TO 'astrnest'@'%';

FLUSH PRIVILEGES;

Tencent Cloud Configuration Guide

1. Register Tencent Cloud Account

Visit Tencent Cloud Official
Click "Free Registration" in top right
Choose registration method (WeChat/QQ/Email/WeCom)
Complete real-name verification (personal/enterprise)

2. Enable Object Storage COS

Login to Tencent Cloud Console
Search "Object Storage" → Enter COS Console
Click "Create Bucket"
Configure bucket:
- Name: astrnest-images (globally unique)
- Region: Select nearest region (e.g., ap-beijing)
- Access Permission: Private read/write (recommended) or Public read/Private write
- Version Control: Enable as needed

3. Get API Keys

Click avatar top right → "Access Management"
Left menu "Access Keys" → "API Key Management"
Click "Create Key"
Record SecretId and SecretKey (Key only shown once, save carefully)

4. Configure Content Review (Optional)

In COS Console → Data Processing CI
Enable "Content Review" service
Create review policy, configure sensitive content detection rules
Get review service SecretId/SecretKey (can share with COS)

5. AstrNest Configuration

Configure in .env or application.yml:

yaml

astrnest:
  storage:
    strategy: TENCENT_COS
    cos:
      enabled: true
      endpoint: https://cos.ap-beijing.myqcloud.com
      region: ap-beijing
      bucket: astrnest-images-1250000000  # Format: name-APPID
      access-key: ${TENCENT_SECRET_ID}
      secret-key: ${TENCENT_SECRET_KEY}
      path-style: false
      accelerate: false

Or in .env:

bash

ASTRNEST_STORAGE_STRATEGY=TENCENT_COS
TENCENT_SECRET_ID=your-secret-id
TENCENT_SECRET_KEY=your-secret-key
TENCENT_REGION=ap-beijing
TENCENT_BUCKET=astrnest-images-1250000000

Alibaba Cloud OSS Configuration

1. Enable OSS Service

Login to Alibaba Cloud Console
Search "Object Storage OSS"
Click "Create Bucket"
Configure:
- Bucket Name: astrnest-images (globally unique)
- Region: Select nearest region (e.g., oss-cn-hangzhou)
- Storage Type: Standard
- Access Permission: Private (recommended)

2. Get AccessKey

Click avatar top right → "AccessKey Management"
Create AccessKey
Record AccessKey ID and AccessKey Secret

3. AstrNest Configuration

yaml

astrnest:
  storage:
    strategy: ALIYUN_OSS
    oss:
      enabled: true
      endpoint: https://oss-cn-hangzhou.aliyuncs.com
      bucket: astrnest-images
      access-key: ${ALIYUN_ACCESS_KEY_ID}
      secret-key: ${ALIYUN_ACCESS_KEY_SECRET}
      cdn-host: https://cdn.your-domain.com  # Optional, configure CDN domain

Huawei OBS Configuration

1. Enable OBS Service

Login to Huawei Cloud Console
Search "Object Storage Service OBS"
Create bucket:
- Bucket Name: astrnest-images
- Region: Select nearest region
- Storage Class: Standard

2. Get AK/SK

Avatar top right → "My Credentials"
"Access Keys" → "Add Access Key"
Download CSV file to save AK/SK

3. AstrNest Configuration

yaml

astrnest:
  storage:
    strategy: HUAWEI_OBS
    obs:
      enabled: true
      endpoint: https://obs.cn-north-4.myhuaweicloud.com
      bucket: astrnest-images
      access-key: ${HUAWEI_ACCESS_KEY}
      secret-key: ${HUAWEI_SECRET_KEY}

Other Cloud Storage Configurations

Upyun USS

yaml

astrnest:
  storage:
    strategy: UPYUN_USS
    upyun:
      enabled: true
      bucket: your-bucket
      operator: your-operator
      password: your-operator-password
      endpoint: https://v0.api.upyun.com
      cdn-host: https://your-domain.b0.upaiyun.com

Qiniu Kodo

yaml

astrnest:
  storage:
    strategy: QINIU_KODO
    qiniu:
      enabled: true
      bucket: your-bucket
      access-key: your-ak
      secret-key: your-sk
      domain: https://your-domain.qiniudn.com

Generic S3 Compatible Storage

For MinIO, AWS S3, Ceph, etc.:

yaml

astrnest:
  storage:
    strategy: S3_COMPATIBLE
    s3:
      enabled: true
      endpoint: https://s3.amazonaws.com
      region: us-east-1
      bucket: your-bucket
      access-key: your-access-key
      secret-key: your-secret-key
      path-style: false

Secret Key Security Management

Environment Variables (Recommended)

bash

# Write to ~/.bashrc or ~/.zshrc
export TENCENT_SECRET_ID=your-secret-id
export TENCENT_SECRET_KEY=your-secret-key

# Apply
source ~/.bashrc

Docker Secrets (Production)

yaml

# docker-compose.yml
secrets:
  cos_secret_id:
    file: ./secrets/cos_secret_id.txt
  cos_secret_key:
    file: ./secrets/cos_secret_key.txt

services:
  backend:
    secrets:
      - cos_secret_id
      - cos_secret_key

Key Rotation Recommendations

Rotate API keys regularly (3-6 months)
Use sub-accounts/temporary credentials, limit permission scope
Enable operation log auditing
Never hardcode keys in code repositories

Troubleshooting

Backend Won't Start

bash

# Check port usage
netstat -tulpn | grep 8080

# Check logs
tail -f /opt/astrnest/logs/app.log

# Check database connection
mysql -u astrnest -p -e "SELECT 1"

Frontend Can't Access API

Check Nginx reverse proxy configuration
Check if backend service is running
Check CORS configuration
Check browser developer tools Network panel

Upload Failed

Check storage directory permission: chmod 755 /opt/astrnest/storage/upload
Check disk space: df -h
Check file size limit (default 20MB)
Check backend error logs

Performance Optimization Recommendations

Enable CDN: Configure Tencent Cloud/Alibaba Cloud CDN for static resources
Database Optimization: Add indexes, configure connection pool
Cache Strategy: Configure Nginx cache, browser cache
Gzip Compression: Enable Nginx gzip compression
HTTP/2: Configure Nginx to support HTTP/2

For more help, please refer to:

Recommended Deployment Guide ​

Table of Contents ​

Prerequisites ​

Environment Requirements ​

Server Requirements ​

Method 1: Traditional Server Deployment ​

1. Build Frontend and Backend ​

Backend Build ​

Frontend Build ​

2. Server Deployment Steps ​

2.1 Upload Files to Server ​

2.2 Configure systemd Service ​

2.3 Nginx Configuration ​

Method 2: aaPanel Deployment ​

1. Install aaPanel ​

2. Install Required Software ​

3. Create Website ​

4. Deploy Backend ​

Method 1: Using Java Project Manager ​

Method 2: Manual Deployment ​

5. Deploy Frontend ​

6. Configure Reverse Proxy ​

7. Configure Rewrite ​

Method 3: Docker Compose Deployment ​

1. Prepare Environment File ​

2. Start Services ​

3. View Logs ​

Database Import Methods ​

Linux/macOS ​

Windows ​

Manual Import (Navicat) ​

Common Permission Issues ​

Tencent Cloud Configuration Guide ​

1. Register Tencent Cloud Account ​

2. Enable Object Storage COS ​

3. Get API Keys ​

4. Configure Content Review (Optional) ​

5. AstrNest Configuration ​

Alibaba Cloud OSS Configuration ​

1. Enable OSS Service ​

2. Get AccessKey ​

3. AstrNest Configuration ​

Huawei OBS Configuration ​

1. Enable OBS Service ​

2. Get AK/SK ​

3. AstrNest Configuration ​

Other Cloud Storage Configurations ​

Upyun USS ​

Qiniu Kodo ​

Generic S3 Compatible Storage ​

Secret Key Security Management ​

Environment Variables (Recommended) ​

Docker Secrets (Production) ​

Key Rotation Recommendations ​

Troubleshooting ​

Backend Won't Start ​

Frontend Can't Access API ​

Upload Failed ​

Performance Optimization Recommendations ​

Recommended Deployment Guide

Table of Contents

Prerequisites

Environment Requirements

Server Requirements

Method 1: Traditional Server Deployment

1. Build Frontend and Backend

Backend Build

Frontend Build

2. Server Deployment Steps

2.1 Upload Files to Server

2.2 Configure systemd Service

2.3 Nginx Configuration

Method 2: aaPanel Deployment

1. Install aaPanel

2. Install Required Software

3. Create Website

4. Deploy Backend

Method 1: Using Java Project Manager

Method 2: Manual Deployment

5. Deploy Frontend

6. Configure Reverse Proxy

7. Configure Rewrite

Method 3: Docker Compose Deployment

1. Prepare Environment File

2. Start Services

3. View Logs

Database Import Methods

Linux/macOS

Windows

Manual Import (Navicat)

Common Permission Issues

Tencent Cloud Configuration Guide

1. Register Tencent Cloud Account

2. Enable Object Storage COS

3. Get API Keys

4. Configure Content Review (Optional)

5. AstrNest Configuration

Alibaba Cloud OSS Configuration

1. Enable OSS Service

2. Get AccessKey

3. AstrNest Configuration

Huawei OBS Configuration

1. Enable OBS Service

2. Get AK/SK

3. AstrNest Configuration

Other Cloud Storage Configurations

Upyun USS

Qiniu Kodo

Generic S3 Compatible Storage

Secret Key Security Management

Environment Variables (Recommended)

Docker Secrets (Production)

Key Rotation Recommendations

Troubleshooting

Backend Won't Start

Frontend Can't Access API

Upload Failed

Performance Optimization Recommendations