CloudPan189 Share 快速开始文档

本文档支持 docker 容器和 Linux 二进制文件两种部署方式。

项目简介

项目地址：https://github.com/xxcheng123/cloudpan189-share

CloudPan189 Share 是一个基于天翼云盘的文件分享管理系统，支持通过订阅链接批量管理和浏览天翼云盘中的共享文件。主要功能包括：

  • 支持天翼云盘扫码登录授权
  • 支持订阅类型和分享类型链接管理
  • 提供 Web 界面进行文件浏览和管理
  • 多线程流式加速浏览视频

环境要求

  • Docker 部署：Docker 环境
  • Linux 部署：Linux / macOS 系统
  • 服务器或本地主机
  • 天翼云盘 APP（用于扫码授权）

安装部署

方式一：Docker 部署（推荐）

1. 创建工作目录

# 创建工作目录和数据目录
mkdir -p /opt/cloudpan189-share
mkdir -p /opt/cloudpan189-share/data

# 切换到工作目录
cd /opt/cloudpan189-share

2. 启动容器

使用官方镜像：

docker run -d \
  --name cloudpan189-share \
  -p 12395:12395 \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  xxcheng123/cloudpan189-share:latest

使用镜像代理（推荐）：

docker run -d \
  --name cloudpan189-share \
  -p 12395:12395 \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  docker.1ms.run/xxcheng123/cloudpan189-share:latest

3. 验证部署

检查容器运行状态：

docker ps | grep cloudpan189-share

查看容器日志：

docker logs cloudpan189-share

方式二：Linux 二进制部署

1. 下载程序

# 下载（请根据您的系统架构选择对应的版本）
# Linux AMD64
curl -L -o share.tar.gz https://github.com/xxcheng123/cloudpan189-share/releases/latest/download/share-linux-amd64.tar.gz

# Linux ARM64
curl -L -o share.tar.gz https://github.com/xxcheng123/cloudpan189-share/releases/latest/download/share-linux-arm64.tar.gz

# macOS AMD64
curl -L -o share.tar.gz https://github.com/xxcheng123/cloudpan189-share/releases/latest/download/share-darwin-amd64.tar.gz

# macOS ARM64 (Apple Silicon)
curl -L -o share.tar.gz https://github.com/xxcheng123/cloudpan189-share/releases/latest/download/share-darwin-arm64.tar.gz

# Windows AMD64
curl -L -o share.zip https://github.com/xxcheng123/cloudpan189-share/releases/latest/download/share-windows-amd64.zip

2. 解压和配置

# 解压
tar -xzf share.tar.gz

# 添加执行权限（如果需要）
chmod +x share-linux-amd64

3. 配置文件设置（可选）

编辑 etc/config.yaml 文件

默认配置如下

port: 12395
dbFile: "data/share.db"
logPath: "logs"

配置说明：

  • port: Web 服务监听端口，默认 12395
  • dbFile: 数据库文件路径，相对于程序运行目录
  • logPath: 日志文件存储路径

4. 运行程序

# 运行（Web 界面将在 http://localhost:12395 可用）
./share-linux-amd64

5. 后台运行（可选）

# 使用 nohup 后台运行
nohup ./share-linux-amd64 > cloudpan189-share.log 2>&1 &

# 或者使用 screen
screen -S cloudpan189-share
./share-linux-amd64
# 按 Ctrl+A+D 退出 screen 会话

# 查看后台进程
ps aux | grep share-linux-amd64

6. 创建系统服务（可选）

创建 systemd 服务文件：

sudo tee /etc/systemd/system/cloudpan189-share.service > /dev/null <<EOF
[Unit]
Description=CloudPan189 Share Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/cloudpan189-share
ExecStart=/opt/cloudpan189-share/share-linux-amd64
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

启用和启动服务：

# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启用服务（开机自启）
sudo systemctl enable cloudpan189-share

# 启动服务
sudo systemctl start cloudpan189-share

# 查看服务状态
sudo systemctl status cloudpan189-share

# 查看服务日志
sudo journalctl -u cloudpan189-share -f

初始化配置

1. 访问管理界面

浏览器访问：http://服务器IP:12395

注意：如果是本地部署，可以访问 http://localhost:12395

2. 系统初始化

首次访问会自动进入初始化页面：

初始化页面

按照提示配置以下信息：

  • 管理员用户名：自定义管理员账号
  • 管理员密码：设置强密码
  • 确认密码：再次输入密码确认

⚠️ 重要提示：请务必记录好管理员账号密码，忘记后需要重新初始化系统！

3. 登录系统

初始化完成后会跳转到登录页面：

登录页面

输入刚才设置的管理员账号密码进行登录。

功能配置

1. 仪表盘概览

登录成功后会进入仪表盘页面：

仪表盘

仪表盘显示系统运行状态和统计信息。

2. 令牌管理

什么是令牌？

令牌是天翼云盘账号的授权凭证，用于获取文件下载地址。为了保护账号安全，系统采用扫码授权方式，令牌有效期为30天。

添加令牌步骤

步骤1：进入令牌管理
点击左侧菜单 "令牌管理" → "添加新令牌"

扫码页面

步骤2：扫码授权

  1. 页面会显示二维码
  2. 打开手机天翼云盘APP
  3. 使用APP扫描二维码
  4. 在APP中确认授权
  5. 点击页面上的"我已扫码"按钮
  6. 等待页面自动刷新完成授权

扫码成功

步骤3：验证令牌
授权成功后，令牌列表会显示新添加的令牌信息：

令牌列表

3. 存储管理

支持的存储类型

系统支持两种类型的天翼云盘链接：

  • 订阅类型：订阅号的内容
  • 分享类型：普通的分享链接

添加存储步骤

步骤1：进入存储管理
点击左侧菜单 "存储管理" → "添加存储"

步骤2：配置存储信息

添加存储

填写以下信息：

  • 存储名称：自定义存储名称，便于识别
  • 存储类型：选择"订阅类型"或"分享类型"
  • 关联令牌：选择之前添加的令牌

订阅类型配置

步骤3：获取订阅用户ID

以天翼云盘官方订阅号为例：

订阅链接：https://content.21cn.com/h5/subscrip/index.html#/pages/own-home/index?uuid=fb90a24ff0be16c92948fb1851b323df

订阅用户ID：fb90a24ff0be16c92948fb1851b323df

配置信息：

  • 订阅用户ID：从订阅链接中提取的UUID（如上例中的 fb90a24ff0be16c92948fb1851b323df）

分享类型配置

分享链接格式示例：

https://cloud.189.cn/t/fieiyq6bErum（访问码：zfr5）

解析分享链接：

  • 分享码：fieiyq6bErum（链接中 /t/ 后面的部分）
  • 访问码：zfr5（括号中的访问码，如果没有则留空）

配置步骤：

分享链接配置

  1. 存储类型：选择"分享类型"
  2. 分享码：填入从链接中提取的分享码（如：fieiyq6bErum）
  3. 访问码：填入访问码（如：zfr5），如果分享链接没有访问码则留空
  4. 关联令牌：选择之前添加的令牌

常见分享链接格式：

链接格式 分享码提取 访问码提取
https://cloud.189.cn/t/ABC123 ABC123 无
https://cloud.189.cn/t/ABC123（访问码：1234） ABC123 1234

⚠️ 注意事项：

  • 分享码是必填项，从分享链接中的 /t/ 后面提取
  • 访问码是可选项，只有当分享链接设置了访问码时才需要填写
  • 如果分享链接已失效或访问码错误，将无法正常获取文件列表

步骤4：确认添加
配置完成后点击"确认添加"按钮。

存储配置

4. 文件浏览

配置完成后，点击左侧菜单 "文件浏览" 即可查看和管理文件：

文件浏览

文件列表

视频播放

文件操作功能

  • 文件预览：支持图片、视频等文件在线预览
  • 文件下载：点击文件可获取下载链接
  • 文件夹浏览：支持多层级文件夹导航
  • 搜索功能：可按文件名搜索文件
  • 视频播放：支持在线播放视频文件，多线程流式加速

存储源切换

如果添加了多个存储源，可以在文件浏览页面顶部切换不同的存储源：

  • 订阅类型存储：显示订阅号的所有共享内容
  • 分享类型存储：显示特定分享链接的文件内容

常见问题

1. 扫码授权失败

问题现象：扫码后提示授权失败或令牌无效

解决方案：

  • 确保使用最新版本的天翼云盘APP
  • 检查网络连接是否正常
  • 重新生成二维码进行扫码
  • 确认在APP中完成了授权操作

2. 文件列表为空

问题现象：添加存储后文件浏览页面显示为空

解决方案：

  • 订阅类型：检查订阅用户ID是否正确
  • 分享类型：检查分享码和访问码是否正确，确认分享链接未失效
  • 确认令牌是否有效且未过期
  • 验证存储配置是否正确
  • 检查网络连接和服务状态

3. 分享链接无法访问

问题现象：分享类型存储显示"无法获取文件列表"或"分享已失效"

解决方案：

  • 检查分享链接是否仍然有效（在浏览器中直接访问测试）
  • 确认分享码提取是否正确
  • 如果有访问码，确认访问码是否正确
  • 检查分享链接是否已过期或被删除
  • 尝试重新获取最新的分享链接

4. 令牌过期处理

问题现象：提示令牌已过期，无法获取文件

解决方案：

  • 进入令牌管理页面
  • 找到过期的令牌
  • 重新扫码更新令牌
  • 或删除旧令牌，添加新令牌

5. 容器启动失败

问题现象：Docker容器无法正常启动

解决方案：

# 检查容器状态
docker ps -a | grep cloudpan189-share

# 查看详细日志
docker logs cloudpan189-share

# 重新启动容器
docker restart cloudpan189-share

# 如果问题持续，删除容器重新创建
docker rm -f cloudpan189-share
# 然后重新运行启动命令

6. 端口冲突

问题现象：提示端口12395已被占用

解决方案：

# 方式1：更换端口
docker run -d \
  --name cloudpan189-share \
  -p 12396:12395 \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  xxcheng123/cloudpan189-share:latest

# 方式2：查找占用端口的进程并停止
lsof -i :12395
kill -9 <PID>

7. 视频播放问题

问题现象：视频无法正常播放或加载缓慢

解决方案：

  • 检查网络连接速度
  • 尝试刷新页面重新加载
  • 确认浏览器支持视频格式
  • 检查令牌是否有效
  • 如果是大文件，请耐心等待缓冲

8. 配置文件问题

问题现象：Linux 部署时程序无法启动或配置不生效

解决方案：

  • 检查 etc/config.yaml 文件是否存在
  • 确认配置文件格式正确（YAML 格式对缩进敏感）
  • 检查数据目录和日志目录是否存在
  • 确认程序有读写相关目录的权限

维护管理

1. 数据备份

重要数据存储在 /opt/cloudpan189-share/data 目录中，建议定期备份：

# 创建备份
tar -czf cloudpan189-backup-$(date +%Y%m%d).tar.gz /opt/cloudpan189-share/data

# 恢复备份
tar -xzf cloudpan189-backup-20240101.tar.gz -C /

2. 系统更新

# 停止当前容器
docker stop cloudpan189-share

# 删除旧容器
docker rm cloudpan189-share

# 拉取最新镜像
docker pull xxcheng123/cloudpan189-share:latest

# 启动新容器
docker run -d \
  --name cloudpan189-share \
  -p 12395:12395 \
  -v /opt/cloudpan189-share/data:/app/data \
  --restart unless-stopped \
  xxcheng123/cloudpan189-share:latest

3. 日志管理

# 查看实时日志
docker logs -f cloudpan189-share

# 查看最近100行日志
docker logs --tail 100 cloudpan189-share

# 清理日志（谨慎操作）
docker logs cloudpan189-share > /dev/null 2>&1

技术支持

如果在使用过程中遇到问题，可以通过以下方式获取帮助：

  • 查看项目官方文档
  • 提交 GitHub Issue
  • 参与社区讨论