# PhotoAlbum

**Repository Path**: sss192/PhotoAlbum

## Basic Information

- **Project Name**: PhotoAlbum
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PhotoAlbum

一个面向内网使用的单二进制相册应用。

项目使用 Go 实现，前后端不分离，启动后即可在局域网内访问。前端资源已嵌入可执行文件，部署时只需要一个可执行程序和同级配置文件。

## 项目特性

- 单二进制运行
- 局域网访问
- 多用户登录与隔离
- 首次启动自动初始化
- 时间线视图
- 自定义相册管理
- 点击与拖拽上传图片
- 自动生成缩略图
- 回收站与恢复
- 图片分享
- 单张下载 / 多选打包下载 / 整相册 ZIP 下载
- 分享图片匿名下载
- 亮色 / 暗色主题
- 桌面端与移动端响应式支持

## 当前已实现功能

### 基础能力

- 使用 Go 实现，前后端不分离
- 前端资源嵌入二进制
- 支持 Linux、macOS、Windows 编译
- 首次启动自动创建配置
- 初始化时自动创建默认管理员用户

### 用户与认证

- 多用户支持
- 用户通过配置文件管理
- `adduser` 命令行添加用户
- 密码使用 bcrypt 哈希保存
- JWT + Cookie 登录态
- 登录 / 退出登录

### 图片能力

- 点击选择文件上传
- 拖拽上传
- 多文件上传
- 上传进度显示
- 上传失败单个重传
- 上传失败一键重传
- 自动提取 EXIF 时间
- 无 EXIF 时使用客户端文件修改时间作为回退时间
- 自动生成缩略图
- EXIF Orientation 方向修正
- 灯箱查看原图
- 左右切换图片
- 显示图片基础信息

### 时间线

- 按日期分组展示
- 无限滚动加载
- 多选
- 按日期一键全选
- 批量删除
- 批量添加到相册
- 批量下载选中图片

### 相册

- 创建相册
- 删除相册
- 相册列表
- 相册封面缩略图
- 相册详情页
- 相册内按日期分组展示
- 相册内无限滚动
- 相册详情刷新恢复
- 整相册 ZIP 下载

### 回收站

- 软删除
- 回收站预览
- 单张恢复
- 批量恢复
- 单张永久删除
- 清空整个回收站

### 分享

- 创建图片分享链接
- 设置分享过期时间
- 分享状态徽章
- 查看 / 复制 / 删除分享链接
- 匿名访问分享页
- 匿名下载分享图片

### 下载

- 单张图片下载
- 多选图片 ZIP 下载
- 整相册 ZIP 下载
- 分享图片匿名下载
- 自动处理 ZIP 内重名文件

### 前端体验

- 亮色 / 暗色主题
- 主题记忆
- 桌面端左侧导航
- 移动端抽屉菜单
- 手机端长按操作菜单
- 上传队列滚动显示

## 技术栈

- Go 1.26
- SQLite（`modernc.org/sqlite`）
- JWT（`github.com/golang-jwt/jwt/v5`）
- 原生 HTML / CSS / JavaScript
- `embed` 嵌入前端资源
- Repository 模式
- SQLite WAL 模式

## 快速开始

### 1. 编译

```bash
go build -o photoalbum .
```

### 2. 首次运行

```bash
./photoalbum
```

如果同级目录下不存在 `config.json`，程序会进入初始化向导，依次提示输入：

- 服务端口
- 图片存储路径
- 默认用户名
- 默认密码

初始化完成后会自动生成配置文件。

### 3. 登录

浏览器访问：

```text
http://127.0.0.1:8080
```

然后使用初始化时创建的用户登录。

## 命令说明

### 添加用户

```bash
./photoalbum adduser
```

按提示输入用户名和密码后，程序会自动把新用户写入配置文件。

## 配置文件示例

```json
{
  "port": 8080,
  "storage_path": "./photos",
  "jwt_secret": "your-random-secret",
  "users": [
    {
      "username": "admin",
      "password_hash": "$2a$10$..."
    }
  ]
}
```

### 配置字段说明

| 字段 | 说明 |
|---|---|
| `port` | 服务监听端口 |
| `storage_path` | 图片与数据库存储目录 |
| `jwt_secret` | JWT 签名密钥 |
| `users` | 用户列表 |
| `users[].username` | 用户名 |
| `users[].password_hash` | bcrypt 密码哈希 |

## 目录结构

```text
.
├── main.go
├── embed.go
├── internal/
│   ├── config/
│   ├── image/
│   ├── server/
│   ├── service/
│   └── storage/
├── web/
│   └── static/
├── README.md
└── README.en.md
```

### 目录说明

| 目录 | 说明 |
|---|---|
| `internal/config` | 配置加载、初始化向导、用户管理 |
| `internal/image` | 图片元数据、缩略图、方向处理 |
| `internal/server` | HTTP 路由与 Handler |
| `internal/service` | 业务逻辑层 |
| `internal/storage` | Repository 抽象与 SQLite 实现 |
| `web/static` | 前端静态资源 |

## 核心交互说明

### 时间线

- 默认进入时间线视图
- 图片按拍摄时间分组显示
- 支持右键 / 长按菜单
- 支持多选、批量删除、批量下载、批量加入相册

### 相册

- 可创建自定义相册
- 图片可加入多个相册
- 相册详情页支持刷新恢复到当前相册
- 相册封面自动展示缩略图

### 回收站

- 删除图片进入回收站
- 支持预览、恢复、批量恢复、永久删除和清空
- 回收站图片仍可显示缩略图

### 分享

- 可对单张图片创建分享链接
- 支持过期时间
- 匿名访问分享页
- 匿名下载分享图片

## 测试

运行全部测试：

```bash
go test ./...
```

构建检查：

```bash
go build ./...
```

## 当前未实现 / 后续规划

- 视频支持
- 搜索功能
- 标签系统
- 页面化用户管理
- 更完整的视频缩略图与转码能力
- `.gitignore` 补充完善

## 说明

这是一个面向内网场景的相册应用，当前优先保证：

- 单二进制部署简单
- 局域网访问方便
- 常用相册能力闭环完整

后续可以在当前 Repository 与 Service 分层基础上逐步增加视频、搜索和更多管理能力。