随机图API系统

一个基于Go和腾讯云COS的高性能随机图片API服务，支持直接返回图片URL，适用于文章缩略图、随机壁纸等场景。本站所有图片，都基于这个随机图API系统，目前测试使用很方便。目前配置防盗链，只允许本站使用。

✨ 特性

🚀 高性能: 使用内存缓存，减少COS API调用
🎲 真随机: 每次请求返回不同的随机图片
🔄 自动刷新: 定时自动刷新图片列表缓存
🌐 CDN加速: 支持自定义CDN域名，提升访问速度
🔧 灵活配置: 支持YAML配置文件和环境变量
📁 多目录支持: 自动发现COS中的所有目录，URL路径直接对应目录名称
🔍 动态发现: 无需预定义配置，系统自动识别新目录
🎯 智能路由: URL路径即目录名称，如 /animation、/two-dimensional

🎯 使用场景

多目录支持

系统自动发现COS中的所有目录，URL路径直接对应目录名称：

<!-- 默认目录 -->
<img src="https://api.xxjsjl.cn/" alt="随机图片">

<!-- 指定目录 -->
<img src="https://api.xxjsjl.cn/animation" alt="动漫图片">
<img src="https://api.xxjsjl.cn/two-dimensional" alt="二次元图片">
<img src="https://api.xxjsjl.cn/api" alt="API图片">

<!-- Markdown -->
![随机图片](https://api.xxjsjl.cn/animation)

<!-- 带时间戳避免缓存 -->
<img src="https://api.xxjsjl.cn/two-dimensional?t=<?php echo time(); ?>" alt="随机图片">

📋 API端点

主要端点（多目录支持）

系统自动发现COS中的所有目录，URL路径直接对应目录名称：

端点	方法	说明	示例
`/`	GET	默认目录随机图片（302重定向）	`https://api.xxjsjl.cn/`
`/{directory}`	GET	指定目录随机图片	`https://api.xxjsjl.cn/animation`
`/api/image`	GET	随机图片（别名）	`https://api.xxjsjl.cn/api/image`
`/api/random`	GET	随机图片（RESTful）	`https://api.xxjsjl.cn/api/random`

目录示例：

/animation - 动漫目录
/two-dimensional - 二次元目录
/api - API目录
/video - 视频目录（如果存在）

参数

参数	说明	可选值	默认值
`format`	返回格式	`redirect` / `json`	`redirect`

管理端点（支持多目录）

端点	方法	说明
`/{directory}/api/count`	GET	获取指定目录图片总数
`/{directory}/api/info`	GET	获取指定目录信息
`/{directory}/api/refresh`	POST	手动刷新指定目录缓存
`/api/count`	GET	获取默认目录图片总数
`/api/info`	GET	获取默认目录信息
`/api/refresh`	POST	手动刷新默认目录缓存
`/health`	GET	健康检查

管理端点

端点	方法	说明
`/api/count`	GET	获取图片总数
`/api/info`	GET	获取API信息
`/api/refresh`	POST	手动刷新缓存
`/health`	GET	健康检查

响应示例

默认模式（重定向）

curl -I https://api.xxjsjl.cn/
# HTTP/1.1 302 Found
# Location: https://imgapi.xxjsjl.cn/api/photo-001.jpg

curl -I https://api.xxjsjl.cn/animation
# HTTP/1.1 302 Found
# Location: https://imgapi.xxjsjl.cn/animation/photo-002.jpg

curl -I https://api.xxjsjl.cn/two-dimensional
# HTTP/1.1 302 Found
# Location: https://imgapi.xxjsjl.cn/two-dimensional/photo-003.jpg

JSON模式

curl "https://api.xxjsjl.cn/animation?format=json"

{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://imgapi.xxjsjl.cn/animation/photo-002.jpg",
    "directory": "animation",
    "timestamp": 1729670220
  }
}

🚀 快速部署

mkdir /data/random-image-api/{configs,bin} -p

下载二进制文件和配置文件

wget https://www.xxjstl.cn/upload/random-image-api-new -O /data/random-image-api/bin/random-image-api-new
wget https://www.xxjstl.cn/upload/config.yaml -O /data/random-image-api/configs/config.yaml

编辑 vim /data/random-image-api/configs/config.yaml，填入你的腾讯云COS配置：

tencent_cos:
  secret_id: "your_secret_id"
  secret_key: "your_secret_key"
  appid: "your_appid"
  bucket: "your-bucket"
  region: "ap-chongqing"
  cdn_domain: "https://your-cdn-domain.com"
  storage_path: "api/"  # 填写默认的存储路径，如：api/

配置启动服务

cat <<EOF> /etc/systemd/system/random-image-api.service
# /etc/systemd/system/random-image-api.service
[Unit]
Description=Random Image API Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/data/random-image-api
ExecStart=/data/api/random-image-api/bin/random-image-api-new -c /data/random-image-api/configs/config.yaml
Restart=on-failure
RestartSec=5s

# 日志
StandardOutput=append:/var/log/random-image-api.log
StandardError=append:/var/log/random-image-api-error.log

# 安全设置
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

启动服务

systemctl daemon-reload
systemctl start random-image-api
systemctl status random-image-api


## 📁 项目结构

.
├── cmd/
│ └── server/
│ └── main.go # 程序入口
├── internal/
│ ├── config/
│ │ └── config.go # 配置管理
│ ├── handler/
│ │ └── image.go # HTTP处理器
│ ├── service/
│ │ └── image_service.go # 业务逻辑
│ └── storage/
│ └── cos.go # COS客户端
├── configs/
│ ├── config.yaml # 配置文件（需创建）
│ └── config.example.yaml # 配置示例
├── Dockerfile # Docker镜像
├── docker-compose.yml # Docker Compose配置
├── Makefile # 构建脚本
├── go.mod # Go模块
└── README.md # 项目文档


## ⚙️ 配置说明

### 服务配置

```yaml
server:
  port: 8080              # 服务端口
  mode: release           # 运行模式: debug/release
  api_domain: "https://api.xxjsjl.cn"  # API域名

COS配置

tencent_cos:
  secret_id: ""           # 腾讯云SecretID
  secret_key: ""          # 腾讯云SecretKey
  appid: ""               # 腾讯云APPID
  bucket: "fenghua"       # 存储桶名称
  region: "ap-chongqing"  # 存储区域
  cdn_domain: "https://imgapi.xxjsjl.cn"  # CDN域名
  # storage_path: "api/"  # 已弃用，使用多目录配置

# 多目录配置（系统自动发现COS目录）
directories:
  # 默认目录（根路径）
  default:
    storage_path: "api/"
    display_name: "默认图库"
  
  # 其他目录将自动从COS中获取
  # 无需预定义，URL路径直接对应目录名称

缓存配置

cache:
  enabled: true           # 是否启用缓存
  ttl: 600                # 缓存时间（秒）

🔧 腾讯云COS配置

1. 创建存储桶

登录腾讯云COS控制台
创建存储桶，如：fenghua-1257845456
选择区域：ap-chongqing（重庆）
访问权限：公有读私有写

2. 获取密钥

访问管理 > API密钥管理
创建密钥，获取 SecretID 和 SecretKey

3. 配置自定义域名（推荐）

存储桶 > 域名与传输管理 > 自定义CDN加速域名
添加域名：imgapi.xxjsjl.cn
开启CDN加速
配置DNS CNAME记录

4. 上传图片（多目录支持）

系统自动发现COS中的所有目录，URL路径直接对应目录名称：

fenghua-1257845304/
├── api/                    # 默认目录: https://api.xxjsjl.cn/
│   ├── photo-001.jpg
│   ├── photo-002.png
│   └── ...
├── animation/              # 动漫目录: https://api.xxjsjl.cn/animation
│   ├── anime-001.jpg
│   ├── anime-002.png
│   └── ...
├── two-dimensional/        # 二次元目录: https://api.xxjsjl.cn/two-dimensional
│   ├── 2d-001.jpg
│   ├── 2d-002.png
│   └── ...
└── video/                  # 视频目录: https://api.xxjsjl.cn/video
    ├── video-001.mp4
    ├── video-002.mov
    └── ...

注意： 系统会自动发现COS中的所有目录，无需手动配置。URL路径就是目录名称。

🌐 域名配置

API服务域名

# DNS A记录
api.xxjsjl.cn -> 你的服务器IP

CDN域名

# DNS CNAME记录
imgapi.xxjsjl.cn -> xxx.cdn.dnsv1.com（腾讯云提供）

📊 监控与维护

查看日志

# Docker
docker logs -f random-image-api

# 本地运行
# 日志输出到stdout

手动刷新缓存

curl -X POST http://localhost:8080/api/refresh

健康检查

curl http://localhost:8080/health

🔒 安全建议

密钥安全
- 使用环境变量存储敏感信息
- 不要将 .env 和 config.yaml 提交到Git
- 生产环境使用密钥管理服务
访问控制
- COS存储桶设置为"公有读私有写"
- 考虑添加API访问频率限制
- 配置防盗链（可选）
CDN加速
- 使用自定义域名+CDN
- 减少COS直接访问
- 降低成本，提升速度
配置edgeone边缘加速
- 腾讯云的免费edge可实现加速

📝 常见问题

Q: 为什么返回"图片列表为空"？

A: 请检查：

COS存储桶中 api/ 目录是否有图片
图片格式是否在允许的扩展名列表中
COS访问权限是否正确配置

Q: 如何添加更多图片？

A: 直接上传图片到COS的 api/ 目录，系统会自动刷新缓存（默认10分钟）。也可以手动调用 /api/refresh 接口立即刷新。

Q: 如何自定义图片分类？

A: 系统自动发现COS中的所有目录。只需在COS中创建目录并上传图片，URL路径就是目录名称：

# 上传图片到对应目录
# 然后就可以通过URL访问：
https://api.xxjsjl.cn/wallpaper
https://api.xxjsjl.cn/anime

无需修改配置文件，系统会自动发现新目录。

目录CONTENT

随机图API系统

随机图API系统

✨ 特性

🎯 使用场景

多目录支持

📋 API端点

主要端点（多目录支持）

参数

管理端点（支持多目录）

管理端点

响应示例

🚀 快速部署

COS配置

缓存配置

🔧 腾讯云COS配置

1. 创建存储桶

2. 获取密钥

3. 配置自定义域名（推荐）

4. 上传图片（多目录支持）

🌐 域名配置

API服务域名

CDN域名

📊 监控与维护

查看日志

手动刷新缓存

健康检查

🔒 安全建议

📝 常见问题

Q: 为什么返回"图片列表为空"？

Q: 如何添加更多图片？

Q: 如何自定义图片分类？

评论区