CloudPan189 Share 快速开始文档

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

项目简介

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

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

支持天翼云盘扫码登录授权
支持订阅类型和分享类型链接管理
提供 Web 界面进行文件浏览和管理
多线程流式加速浏览视频
STRM文件生成：自动为视频文件生成STRM文件，完美兼容Emby、Jellyfin、Plex等媒体服务器 ⚠️ 测试功能
WebDAV写入支持：支持通过WebDAV协议上传、删除真实文件 ⚠️ 测试功能
增强的文件管理：完整的文件锁定机制和权限控制

⚠️ 重要提示：STRM文件生成和WebDAV写入功能目前处于测试阶段，使用过程中如遇到问题请及时通过 GitHub Issue 反馈。

环境要求

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

安装部署

方式一：Docker 部署（推荐）

1. 创建工作目录

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

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

2. 启动容器

使用官方镜像：

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

使用镜像代理（推荐）：

docker run -d \
  --name cloudpan189-share \
  -p 12395:12395 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/datadir:/app/datadir \
  --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"
logFile: "logs/share.log"
fileDir: "datadir"

配置说明：

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

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：扫码授权

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

步骤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（括号中的访问码，如果没有则留空）

配置步骤：

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

常见分享链接格式：

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

⚠️ 注意事项：

分享码是必填项，从分享链接中的 /t/ 后面提取

访问码是可选项，只有当分享链接设置了访问码时才需要填写

如果分享链接已失效或访问码错误，将无法正常获取文件列表

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

4. 文件浏览

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

文件操作功能

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

存储源切换

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

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

5. 系统设置

点击左侧菜单 "系统设置" 可以配置系统的各项功能：

STRM文件生成设置

什么是STRM文件？ STRM文件是一种包含媒体文件URL的文本文件，被Emby、Jellyfin、Plex等媒体服务器用来播放远程媒体内容。

配置步骤：

进入系统设置页面
找到"STRM文件生成"选项
开启该功能后，系统会自动为支持的视频文件生成对应的STRM文件
可以在"STRM支持文件格式"中自定义支持的视频格式

支持的默认格式：

常见视频格式：mp4, mkv, avi, mov, wmv, flv, webm, m4v
高清格式：ts, mts, m2ts, m2t, mxf
其他格式：3gp, f4v, vob, ogv, divx, xvid, rm, rmvb等

使用场景：

配合Emby/Jellyfin/Plex等媒体服务器使用
通过WebDAV挂载到媒体服务器的媒体库目录
实现远程媒体内容的本地化管理

WebDAV写入权限设置

功能说明： 控制是否允许通过WebDAV协议进行文件写入和删除操作。

配置选项：

开启：允许通过WebDAV上传、修改、删除真实文件
关闭：WebDAV仅提供只读访问，无法进行写入操作

注意事项：

此功能仅影响真实文件，不包括挂载的分享文件和STRM等虚拟文件
开启写入权限后，建议配合用户认证功能使用
删除父级文件夹时，其中的文件也会被删除

其他重要设置

多线程流式下载：

使用多个连接并发下载视频片段
可配置线程数（1-64）和块大小（512KB-8MB）
优先级高于本地代理设置

用户认证：

控制WebDAV访问是否需要用户登录
建议在生产环境中开启

本地代理：

服务器代为获取资源再转发给用户
可解决某些网络环境下的访问问题

自动刷新：

定期自动刷新挂载的文件列表
可配置刷新间隔（5-120分钟）

常见问题

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 格式对缩进敏感）
检查数据目录和日志目录是否存在
确认程序有读写相关目录的权限

9. STRM文件相关问题

问题现象：STRM文件无法生成或媒体服务器无法识别

解决方案：

确认在系统设置中已开启"STRM文件生成"功能
检查视频文件格式是否在支持列表中
验证WebDAV挂载路径是否正确
确认媒体服务器有读取STRM文件的权限
尝试使用"重建STRM文件"功能重新生成

问题现象：媒体服务器播放STRM文件时提示无法访问

解决方案：

检查媒体服务器网络是否能访问CloudPan189 Share服务
确认系统设置中的"基础URL"配置正确
验证天翼云盘令牌是否有效
检查防火墙是否阻止了媒体服务器的访问

10. WebDAV写入权限问题

问题现象：无法通过WebDAV上传或删除文件

解决方案：

确认在系统设置中已开启"WebDAV写入权限"
检查用户是否有足够的权限（如果开启了用户认证）
验证WebDAV客户端是否支持写入操作
确认要操作的是真实文件，而非挂载的分享文件

问题现象：上传文件后无法在Web界面中看到

解决方案：

刷新Web界面的文件列表
检查文件是否上传到正确的目录
确认文件上传过程中没有出现错误
查看系统日志了解详细错误信息

11. 多线程流式下载问题

问题现象：视频播放仍然缓慢或卡顿

解决方案：

确认已开启"多线程流式下载"功能
适当调整线程数，过多的线程可能导致性能下降
调整块大小，较大的块可能提升性能但增加内存使用
检查网络带宽和服务器性能
确认天翼云盘令牌有效且未被限速

问题现象：开启多线程后系统资源占用过高

解决方案：

降低多线程流线程数设置
减小块大小以降低内存使用
监控服务器CPU和内存使用情况
考虑在服务器性能较低时关闭此功能

维护管理

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 \
  -v /opt/cloudpan189-share/datadir:/app/datadir \
  --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
参与社区讨论

FilesExpand file tree

1.quick_start.md

Latest commit

History

1.quick_start.md

File metadata and controls

CloudPan189 Share 快速开始文档

项目简介

环境要求

安装部署

方式一：Docker 部署（推荐）

1. 创建工作目录

2. 启动容器

3. 验证部署

方式二：Linux 二进制部署

1. 下载程序

2. 解压和配置

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

4. 运行程序

5. 后台运行（可选）

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

初始化配置

1. 访问管理界面

2. 系统初始化

3. 登录系统

功能配置

1. 仪表盘概览

2. 令牌管理

什么是令牌？

添加令牌步骤

3. 存储管理

支持的存储类型

添加存储步骤

订阅类型配置

分享类型配置

4. 文件浏览

文件操作功能

存储源切换

5. 系统设置

STRM文件生成设置

WebDAV写入权限设置

其他重要设置

常见问题

1. 扫码授权失败

2. 文件列表为空

3. 分享链接无法访问

4. 令牌过期处理

5. 容器启动失败

6. 端口冲突

7. 视频播放问题

8. 配置文件问题

9. STRM文件相关问题

10. WebDAV写入权限问题

11. 多线程流式下载问题

维护管理

1. 数据备份

2. 系统更新

3. 日志管理

技术支持