快速开始指南

本指南将帮助您快速部署和运行 AstrNest 图床系统。

🚀 快速体验

如果您想快速体验 AstrNest 的功能，可以按照以下步骤快速启动：

bash

# 克隆项目
git clone <repository-url>
cd AstrNest

# 复制环境变量文件
cp .env.example .env

# 编辑 .env 文件，配置数据库密码等必要参数
# 建议使用强密码替换默认密码

# 启动所有服务（Docker Compose）
docker compose --env-file .env up -d

访问地址：http://localhost

默认管理员账号：

用户名：admin
密码：chenxi123

⚠️ 安全提示：出于安全考虑，强烈建议在首次登录后立即修改默认管理员密码。

环境要求

在开始之前，请确保您的系统满足以下要求：

基础环境

Docker: 20.10+ 和 Docker Compose 2.0+
JDK 21（传统部署方式需要）
Node.js 18+ 与 npm 9+（传统部署方式需要）
MySQL 5.7+/8.0（传统部署方式需要）
可选：curl、Nginx 等部署辅助工具

操作系统支持

Windows 10/11（支持 WSL2）
macOS 10.15+
Linux（Ubuntu 18.04+, CentOS 7+, 其他主流发行版）

🚀 一键启动（Docker Compose 推荐）

1. 克隆项目

bash

git clone <repository-url>
cd AstrNest

2. 配置环境变量

bash

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，修改以下关键配置：
# - MYSQL_ROOT_PASSWORD: MySQL root 密码
# - MYSQL_PASSWORD: MySQL 应用密码
# - ASTRNEST_ADMIN_PASSWORD: 管理员密码（建议修改）
# - PUBLIC_SITE_URL: 您的站点域名
# - VITE_API_BASE_URL: 前端访问后端的地址

3. 启动服务

bash

# 启动所有服务
docker compose --env-file .env up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

4. 访问应用

前端地址：http://localhost
后端地址：http://localhost:8080
API文档：http://localhost:8080/swagger-ui/index.html

默认管理员账号

用户名：admin
密码：chenxi123

📋 详细步骤说明

Docker Compose 部署详细说明

服务架构

Docker Compose 会启动以下服务：

服务	容器名	端口	说明
MySQL	astrnest-mysql	3306	数据库服务
Backend	astrnest-backend	8080	Spring Boot 后端服务
Frontend	astrnest-frontend	80	Vue 3 前端服务

数据持久化

默认配置下，数据会持久化到以下位置：

MySQL 数据：Docker volume mysql_data
上传文件：./storage/upload 目录

数据库初始化

如果使用传统部署方式，需要手动初始化数据库：

bash

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

# Windows（使用 init_windows.sql）
mysql -u root -p < backend/db/init_windows.sql

该脚本会自动完成以下操作：

创建 astrnest 数据库与专用账号
创建所有核心数据表
预置默认角色和超级管理员账号
配置系统参数和内容策略

💡 提示：init_windows.sql 是专门为 Windows/Navicat 优化的版本，移除了可能导致导入失败的动态 SQL。

后端服务详细配置

环境变量配置（推荐）

您可以使用环境变量覆盖默认配置：

bash

export ASTRNEST_DB_URL="jdbc:mysql://localhost:3306/astrnest?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai"
export ASTRNEST_DB_USERNAME="astrnest"
export ASTRNEST_DB_PASSWORD="your_password"
export ASTRNEST_ADMIN_USERNAME="admin"
export ASTRNEST_ADMIN_PASSWORD="StrongerPass123!"

存储策略配置

默认使用本地存储，如需使用云存储，修改 .env 或 application.yml：

yaml

# 阿里云 OSS
ASTRNEST_STORAGE_STRATEGY=ALIYUN_OSS

# 腾讯云 COS
ASTRNEST_STORAGE_STRATEGY=TENCENT_COS

# 本地存储（默认）
ASTRNEST_STORAGE_STRATEGY=LOCAL

前端服务详细配置

环境变量配置

前端通过环境变量指定后端地址：

bash

# 开发环境
VITE_API_BASE_URL="http://localhost:8080"

# 生产环境构建
VITE_API_BASE_URL="https://api.yourdomain.com"
VITE_PUBLIC_ASSET_BASE="https://cdn.yourdomain.com/upload"

🐳 Docker 常用命令

服务管理

bash

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f [service-name]

数据备份

bash

# 备份数据库
docker compose exec mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} astrnest > backup-$(date +%Y%m%d).sql

# 备份上传文件
cp -r storage/upload backup/upload-$(date +%Y%m%d)

🔧 常见问题排查

端口冲突问题

如果端口被占用，可以修改 docker-compose.yml 中的端口映射：

yaml

services:
  backend:
    ports:
      - "8081:8080"  # 修改宿主机端口
  
  frontend:
    ports:
      - "8080:80"    # 修改宿主机端口

数据库连接失败

检查数据库服务是否正常运行：

bash

# 检查 MySQL 容器状态
docker compose ps mysql

# 查看 MySQL 日志
docker compose logs mysql

# 测试数据库连接
docker compose exec mysql mysql -u astrnest -p -e "SHOW DATABASES;"

权限问题（Linux/macOS）

如果遇到文件权限问题：

bash

# 修改存储目录权限
sudo chown -R $USER:$USER ./storage

# 或者使用 Docker 用户运行
# 在 docker-compose.yml 中添加 user: "1000:1000"

📊 验证安装

健康检查

访问健康检查端点验证服务状态：

bash

# 后端健康检查
curl http://localhost:8080/actuator/health

# 预期响应
{"status":"UP"}

功能测试

登录测试：使用默认管理员账号登录 http://localhost
上传测试：尝试上传一张图片
API测试：访问 Swagger UI 测试 API 接口

🚀 生产环境部署

必改配置清单

部署到生产环境前，请务必修改以下配置：

配置项	位置	说明
数据库密码	`.env`	使用强密码
管理员密码	`.env`	修改默认密码
站点域名	`.env`	配置真实域名
JWT Secret	后端配置	使用随机字符串
AI 审核密钥	`.env` 或后台	腾讯云 COS CI 密钥

SSL/HTTPS 配置

推荐使用 Nginx 反向代理配置 HTTPS：

nginx

server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /api/ {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /upload/ {
        proxy_pass http://localhost:8080/upload/;
        proxy_set_header Host $host;
        expires 7d;
        add_header Cache-Control "public";
    }
}

📝 下一步

成功启动 AstrNest 后，建议您：

修改默认密码：立即修改管理员密码
配置存储策略：根据需求配置本地或云存储
设置域名：配置自定义域名和 SSL 证书
配置 AI 审核：在后台配置腾讯云 COS CI 审核
备份策略：制定数据备份和恢复计划
监控配置：配置系统监控和告警

🆘 获取帮助

如果在部署过程中遇到问题，请参考：

🎉 恭喜！您已成功启动 AstrNest 图床系统！

快速开始指南 ​

🚀 快速体验 ​

环境要求 ​

基础环境 ​

操作系统支持 ​

🚀 一键启动（Docker Compose 推荐） ​

1. 克隆项目 ​

2. 配置环境变量 ​

3. 启动服务 ​

4. 访问应用 ​

默认管理员账号 ​

📋 详细步骤说明 ​

Docker Compose 部署详细说明 ​

服务架构 ​

数据持久化 ​

数据库初始化 ​

后端服务详细配置 ​

环境变量配置（推荐） ​

存储策略配置 ​

前端服务详细配置 ​

环境变量配置 ​

🐳 Docker 常用命令 ​

服务管理 ​

数据备份 ​

🔧 常见问题排查 ​

端口冲突问题 ​

数据库连接失败 ​

权限问题（Linux/macOS） ​

📊 验证安装 ​

健康检查 ​

功能测试 ​

🚀 生产环境部署 ​

必改配置清单 ​

SSL/HTTPS 配置 ​

📝 下一步 ​

🆘 获取帮助 ​

快速开始指南

🚀 快速体验

环境要求

基础环境

操作系统支持

🚀 一键启动（Docker Compose 推荐）

1. 克隆项目

2. 配置环境变量

3. 启动服务

4. 访问应用

默认管理员账号

📋 详细步骤说明

Docker Compose 部署详细说明

服务架构

数据持久化

数据库初始化

后端服务详细配置

环境变量配置（推荐）

存储策略配置

前端服务详细配置

环境变量配置

🐳 Docker 常用命令

服务管理

数据备份

🔧 常见问题排查

端口冲突问题

数据库连接失败

权限问题（Linux/macOS）

📊 验证安装

健康检查

功能测试

🚀 生产环境部署

必改配置清单

SSL/HTTPS 配置

📝 下一步

🆘 获取帮助