# app-cloud

**Repository Path**: gudujohn/app-cloud

## Basic Information

- **Project Name**: app-cloud
- **Description**: 个人云数据存储平台，App 通过 HTTP/MQTT 上传同步数据。
Java 8 · SpringBoot 2.7 · SQLite · Layui · Moquette MQTT · Apache 2.0
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# App Cloud

个人应用云数据存储平台。App 配置平台地址后，可上传/同步云数据。基于文件存储，文件夹管理应用。提供 Web 管理后台和 MQTT 实时上报。

## 技术栈

- **后端:** SpringBoot 2.7.18 / JDK 1.8 / Maven
- **数据库:** SQLite（文件数据库，无需外部服务）
- **前端:** Layui 静态页面 SPA 架构（admin/index.html 为框架页）
- **认证:** JWT（管理界面）+ JWT App Token（应用接入）
- **MQTT:** Moquette 内嵌 Broker（端口可配置，默认 1883）
- **加密:** AES-256-GCM 传输加密
- **跨域:** CORS 全放行（Token 认证，无 CSRF 风险）

## 快速启动

```bash
mvn spring-boot:run
```

访问 `http://localhost:8080`，首次启动进入管理员配置引导。

## 管理后台

登录后进入 `/admin/index.html`（SPA 单页框架），侧边栏包含：

| 页面 | 功能 |
|------|------|
| 控制台 | 用户数、MQTT 连接数/状态统计 |
| 用户管理 | 用户 CRUD、重置密码 |
| 应用数据浏览 | 按用户 → 应用 → 文件三级浏览，查看 appKey/Secret |
| MQTT 管理 | Broker 状态、在线客户端、订阅主题、连接说明 |
| 系统配置 | 单用户模式、调试限制开关 |

Header 下拉菜单支持修改密码和退出登录。

## 数据存储结构

```
{platform.data-dir}/
├── app-cloud.db          # SQLite 数据库
└── users/
    └── {username}/
        └── {app-name}/        # 每个应用一个文件夹
            ├── config.json    # 默认配置
            ├── backups/       # 二级目录（示例）
            │   └── data.zip
            ├── logs/          # 二级目录（示例）
            │   └── today.txt
            └── reports/       # 周期上报目录
                ├── heartbeat_2026-06-03T14.log
                └── event_2026-06-03.log
```

默认 `platform.data-dir=./data`，可在 `application.properties` 中修改。

## API 概览

### 管理接口（JWT 认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/auth/login | 登录，返回 JWT + userId |
| GET | /api/setup/status | 首次配置状态 |
| POST | /api/setup/init | 初始化管理员 |
| GET/POST/DELETE | /api/admin/users | 用户管理 |
| PUT | /api/admin/users/{id}/password | 重置用户密码 |
| PUT | /api/admin/profile/password | 修改自己的密码 |
| GET | /api/admin/config | 获取系统配置 |
| PUT | /api/admin/config | 保存系统配置 |
| GET | /api/admin/mqtt/* | MQTT 状态/客户端/主题/统计 |
| GET | /api/admin/users/{id}/apps | 查看用户应用列表 |
| GET | /api/admin/users/{id}/apps/detail | 查看用户应用详情(appKey/Secret) |
| DELETE | /api/admin/users/{userId}/apps/{appName} | 删除应用（需先清空文件） |
| GET | /api/admin/users/{userId}/apps/{appName}/files | 查看应用文件列表 |
| GET | /api/admin/users/{userId}/apps/{appName}/files/** | 查看文件内容 |
| DELETE | /api/admin/users/{userId}/apps/{appName}/files/** | 删除应用文件 |

### 用户自助接口（JWT 认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/user/apps | 查看自己的应用列表 |
| GET | /api/user/apps/detail | 查看自己的应用详情 |
| DELETE | /api/user/apps/{appName} | 删除自己的应用（需先清空文件） |
| GET | /api/user/apps/{appName}/files | 查看应用文件列表 |
| GET | /api/user/apps/{appName}/files/** | 查看文件内容 |
| DELETE | /api/user/apps/{appName}/files/** | 删除应用文件 |

### 应用接入 API（详细文档见 [API.md](docs/API.md)）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/app/register | 应用自主注册 |
| POST | /api/app/login | 应用登录换取 JWT + AES Key |
| POST | /api/app/token/refresh | Token 续期 |
| POST | /api/app/config | 配置上传（new/overwrite/append） |
| GET | /api/app/config | 获取配置（支持 ?file=） |
| POST | /api/app/upload | 文件上传（二级目录 + 加密） |
| GET | /api/app/sync | 文件列表（支持 dir/recursive） |
| GET | /api/app/download/... | 下载文件（多级路径） |
| POST | /api/app/report | 周期上报（单条/批量） |
| MQTT | `cloud/{app-name}/report` | MQTT 实时上报（JWT 认证） |

## 系统配置项

| 配置键 | 说明 |
|------|------|
| `single.user.mode` | 单用户模式（开启后不允许创建子账号和应用注册新用户） |
| `debug.restriction` | 调试限制（开启后阻止 F12/DevTools） |
| `mqtt.enabled` | MQTT Broker 启用/关闭 |
| `mqtt.port` | MQTT 监听端口（默认 1883） |

## Docker 部署（NAS）

```bash
mvn clean package
docker build -t app-cloud -f docker/Dockerfile .
docker run -d -p 8080:8080 -p 1883:1883 -v /your/nas/data:/data app-cloud
```

或使用 docker-compose：

```bash
DATA_DIR=/your/nas/data docker-compose up -d
```

数据目录 `/data` 需挂载到 NAS 持久化存储，MQTT 端口 1883 需映射。