常见问题解答 (FAQ)

安装与配置

Q: 如何修改默认的管理员密码？

A: 出于安全考虑，强烈建议在安装后修改默认管理员密码（admin/chenxi123）。以下是完整的修改步骤：

方法1：环境变量设置（推荐用于新部署）

在启动服务前设置环境变量：

export ASTRNEST_ADMIN_PASSWORD=your_new_password
# 或添加到 .env 文件
ASTRNEST_ADMIN_PASSWORD=your_new_password

方法2：管理界面修改（推荐用于已运行系统）

1. 使用默认凭据（admin/chenxi123）登录系统
2. 导航到用户管理 → 管理员账户
3. 点击"修改密码"并设置新的安全密码

方法3：直接数据库修改

连接到 MySQL 并执行：

UPDATE users SET password = '<新_bcrypt_哈希>' WHERE username = 'admin';

方法4：完整同步修改（推荐用于生产环境）

步骤1：生成新密码的 bcrypt 哈希 在任何安装了 Python 的机器上执行：

python - <<'PY'
import bcrypt, sys
print(bcrypt.hashpw(b"your_new_password", bcrypt.gensalt()).decode())
PY

步骤2：更新数据库

UPDATE users SET password = '<新_bcrypt_哈希>' WHERE username = 'admin';

重要安全注意事项：

• 在生产环境中始终使用强密码
• 考虑实施密码轮换策略
• 启用双因素认证以增强安全性

Q: 数据库连接失败怎么办？

A: 检查以下配置项：

1. 确认数据库服务运行状态：

   # Docker 部署
   docker compose ps mysql
   docker compose logs mysql
   
   # 传统部署
   systemctl status mysql
   # 或
   service mysql status

2. 验证数据库连接参数：

   • 检查 .env 或 application.yml 中的数据库 URL、用户名、密码
   • 确认数据库名称和字符集设置正确（应为 utf8mb4）
   • 检查防火墙设置，确保端口 3306 可访问

3. 测试数据库连接：

   mysql -u astrnest -p -h localhost astrnest

4. 常见错误 1044/42000： 如果账号能登录但无库权限，请用 root 执行：

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

Q: 如何配置云存储？

A: 修改 .env 中的存储配置：

# 阿里云 OSS
ASTRNEST_STORAGE_STRATEGY=ALIYUN_OSS
ALIYUN_ACCESS_KEY=your-access-key
ALIYUN_SECRET_KEY=your-secret-key

# 腾讯云 COS
ASTRNEST_STORAGE_STRATEGY=TENCENT_COS
TENCENT_SECRET_ID=your-secret-id
TENCENT_SECRET_KEY=your-secret-key

# AWS S3
ASTRNEST_STORAGE_STRATEGY=S3_COMPATIBLE
AWS_ACCESS_KEY=your-access-key
AWS_SECRET_KEY=your-secret-key

或在 application.yml 中配置详细参数，详见 安装配置指南。

Q: Windows 下如何导入数据库？

A: Windows 用户请使用专门的 Windows 版本初始化脚本：

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

init_windows.sql 移除了 DELIMITER 等 Windows/Navicat 不兼容的语法。导入前请先用 root 创建数据库：

CREATE DATABASE IF NOT EXISTS astrnest CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

使用问题

Q: 上传文件大小限制是多少？

A: 默认配置：

• 单个文件大小：最大 20MB（与数据库 CHECK 约束匹配）
• 批量上传数量：最多 10 个文件
• 每日上传限额：用户默认可配置

修改限制：

# .env
ASTRNEST_MULTIPART_MAX_FILE_SIZE=20MB
ASTRNEST_MULTIPART_MAX_REQUEST_SIZE=20MB

⚠️ 注意：文件大小限制必须 ≤20MB，否则会与数据库 CHECK (size <= 20971520) 冲突。

Q: 如何设置图片的公开/私有权限？

A: 有以下几种方式：

1. 上传时设置：在上传界面选择可见性
2. 上传后修改：在图片管理页面修改可见性
3. 批量设置：支持批量修改多张图片的可见性
4. API 设置：通过 API 接口修改

Q: 访客点赞功能如何启用？

A: 在系统配置中启用：

1. 以管理员身份登录
2. 进入"系统配置"页面
3. 找到"访客点赞"设置
4. 启用该功能并保存

访客需要在请求头中添加：

X-Chenxi-Visitor: visitor_unique_id

部署问题

Q: Docker 部署时如何持久化数据？

A: 使用 Docker volumes：

# docker-compose.yml
services:
  mysql:
    image: mysql:8.0
    volumes:
      - mysql_data:/var/lib/mysql
      - ./backend/db/init.sql:/docker-entrypoint-initdb.d/init.sql
    
  backend:
    volumes:
      - ./storage/upload:/storage/upload

volumes:
  mysql_data:

Q: 如何配置 HTTPS？

A: 推荐使用 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/;
        expires 7d;
        add_header Cache-Control "public";
    }
}

Q: 如何配置 Nginx 反向代理以同时支持前端开发和上传资源访问？

A: 需要为 /upload/ 做单独的 location：

server {
    listen 80;
    server_name astrnest.luminouschenxi.net;
    
    # 前端开发服务器
    location / {
        proxy_pass http://127.0.0.1:5173;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # 上传资源 - 直接映射到本地目录或转发到后端
    location /upload/ {
        alias /www/wwwroot/Project/AstrNest/storage/upload/;
        # 或 proxy_pass http://127.0.0.1:8080/upload/;
        autoindex off;
        expires 7d;
        add_header Cache-Control "public";
    }
    
    # API 接口
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Q: Maven 构建时出现 "Operation not permitted" 权限错误？

A: 这是常见的权限问题，通常发生在以下情况：

1. 目标目录权限不足：

   # 检查 target 目录权限
   ls -la target/classes/
   
   # 解决方案：删除并重新创建 target 目录
   rm -rf target
   ./mvnw clean compile

2. 文件被其他进程占用：

   # 检查是否有其他 Java 进程在运行
   ps aux | grep java
   
   # 杀死相关进程
   kill -9 <pid>

3. Windows 下使用管理员权限运行 PowerShell 或 IDE

Q: Windows 下启动后端出现中文乱码？

A: 这是终端编码与 Java 输出编码不一致导致的。

推荐做法（Windows Terminal / PowerShell）：

chcp 65001
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
cd backend
.\mvnw.cmd spring-boot:run

IDE 控制台（IntelliJ IDEA）：

• 将 Settings > Editor > File Encodings 设置为 UTF-8
• 运行配置里确保控制台编码为 UTF-8

Q: Spring Boot 应用启动失败，端口 8080 已被占用？

A: 找出并终止占用进程：

# 查找占用 8080 端口的进程
sudo lsof -i :8080
# 或
sudo ss -lptn 'sport = :8080'

# 杀死进程
kill -9 <PID>

# 或更改 Spring Boot 端口
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081

Q: 日志出现 "No converter for ApiErrorResponse with preset Content-Type 'video/mp4'"？

A: 这是正常的，不影响服务运行。含义是：请求的是视频资源，但中途抛异常后框架想返回 JSON 错误体，由于响应头 Content-Type 已经是 video/mp4，就会出现这种报错。

处理建议：

• 确认资源文件确实存在、存储路径配置正确
• 这类报错通常不影响服务启动，但会导致那一次请求返回失败

Q: 日志出现 "Cannot run program 'ffmpeg'"？

A: 后端在生成视频封面时找不到 ffmpeg，一般不影响后端启动，但会导致视频封面生成失败。

解决方案：

• 方案 A（推荐）：安装 ffmpeg 并确保命令行可直接执行 ffmpeg
• 方案 B：如果暂时不需要视频封面，设置 ASTRNEST_VIDEO_THUMBNAIL_ENABLED=false

开发问题

Q: pip、Maven、npm 这三种包管理器有什么区别？

A: 三者主要区别如下：

包管理器	语言生态	主要用途	配置文件	包仓库
pip	Python	Python 包管理	requirements.txt pyproject.toml	PyPI
Maven	Java	Java 项目构建和依赖管理	pom.xml	Maven Central
npm	JavaScript/Node.js	Node.js 包管理	package.json	npm Registry

核心哲学对比：

• Maven (Java)："约定优于配置" - 强调一致性、共享、可重用性。依赖是项目编译时需要的库。
• npm (Node.js)："项目隔离自洽" - 强调独立性、确定性、可移植性。依赖是项目运行时需要的模块。

Q: 如何扩展新的存储驱动？

A: 实现 StorageService 接口：

@Component
public class CustomStorageService implements StorageService {
    
    @Override
    public String upload(MultipartFile file, String path) {
        // 实现上传逻辑
    }
    
    @Override
    public boolean delete(String objectKey) {
        // 实现删除逻辑
    }
    
    // 其他方法实现
}

然后在配置中启用：

astrnest:
  storage:
    strategy: CUSTOM

Q: 前端如何自定义主题？

A: 修改 Tailwind CSS 配置：

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        }
      }
    }
  }
}

故障排除

Q: 服务启动失败，如何查看日志？

A: 查看应用日志：

# Docker 部署
docker compose logs -f backend
docker compose logs -f mysql

# 传统部署 - 后端日志
cd backend
./mvnw spring-boot:run

# 传统部署 - 前端日志
cd frontend
npm run dev

Q: 上传文件失败，如何排查？

A: 检查以下方面：

1. 文件大小：确认未超过 20MB 限制
2. 文件类型：检查是否支持该格式
3. 存储空间：确认存储空间充足
4. 网络连接：检查网络状况
5. 权限设置：确认有写入权限
6. AI 审核：检查腾讯云 COS CI 配置是否正确

Q: API 调用返回 403 错误？

A: 可能的原因：

1. 认证失败：检查 API 密钥或 token
2. 权限不足：确认用户角色有相应权限
3. IP 限制：检查 IP 白名单设置
4. 频率限制：确认未超过调用限额

Q: AI 内容审核不生效？

A: 检查以下配置：

1. 腾讯云密钥：确认 ASTRNEST_AI_TENCENT_SECRET_ID 和 SECRET_KEY 正确
2. 存储桶配置：确认 Bucket 名称和 Region 正确
3. 存储策略：AI 审核仅在腾讯云 COS 存储策略下生效
4. 后台配置：在「系统配置 > AI 智能审核」中检查配置是否启用

性能优化

Q: 如何提高图片加载速度？

A: 优化建议：

1. 启用 CDN：配置内容分发网络
2. 图片压缩：启用自动图片压缩
3. 懒加载：实现图片懒加载功能
4. 缓存策略：配置浏览器和服务器缓存
5. 对象存储：使用阿里云 OSS 或腾讯云 COS

Q: 数据库性能如何优化？

A: 数据库优化：

1. 索引优化：为常用查询字段添加索引
2. 查询优化：避免 N+1 查询问题
3. 分表分库：大数据量时考虑分表
4. 缓存策略：使用 Redis 缓存热点数据

安全相关

Q: 如何加强系统安全性？

A: 安全建议：

1. 定期更新：及时更新依赖库
2. 密码策略：强制使用强密码，修改默认密码
3. 访问控制：限制管理界面访问 IP
4. 日志审计：启用详细的操作日志
5. 备份策略：定期备份重要数据
6. HTTPS：生产环境必须启用 HTTPS

Q: 如何防止恶意上传？

A: 防护措施：

1. 文件类型检查：严格限制上传文件类型
2. AI 内容审查：启用腾讯云 COS CI 自动内容检测
3. 人工审核：重要内容人工审核
4. 频率限制：限制单个用户上传频率
5. 文件大小限制：限制单文件最大 20MB

---

🆘 更多帮助

如果以上问题未能解决您的问题，请：

1. 查看日志：仔细阅读错误日志信息
2. 搜索文档：在文档中搜索相关关键词
3. 查看配置指南：安装配置指南
4. 社区求助：在 GitHub Issues 提问
5. 联系支持：通过官方渠道获取技术支持

📞 获取帮助

如果您需要进一步的帮助，可以通过以下方式联系我们：

• 📖 查看文档 - 详细了解项目功能
• 🚀 快速开始 - 立即开始使用
• ❓ 常见问题 - 解决常见问题
• 🔧 API文档 - 查看完整的API接口
• 🐛 报告问题 - 反馈bug或建议

---

💡 小贴士：遇到问题时，先查看日志文件通常能快速定位问题原因。