baidu-autosave-fixed/修正版使用说明.txt at main · happy100-dotcom/baidu-autosave-fixed · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
百度网盘自动转存修正版——安装与操作说明
生成日期：2026-08-06
审计基线：happy100-dotcom/baidu-autosave main，提交 018ca55545521cedce827d80bac86f3e7487dd9b

一、先说结论

本压缩包已经包含修正后的源码，不需要把任何 GitHub 令牌交给别人，也不会自动修改你的 GitHub。
推荐直接使用 Docker Compose 从本压缩包源码构建，不能再引用 kokojacket/baidu-autosave:latest，否则运行的是原版镜像，不是本修正版。

二、【硬性必须】首次安装

1. 撤销曾经公开发送过的 GitHub 令牌。
   GitHub → Settings → Developer settings → Personal access tokens → Revoke。
   即使令牌属于小号，只要在聊天中发出过，就必须视为已泄露。

2. 解压本压缩包，进入项目目录。

3. 创建环境变量文件：
   cp .env.example .env

4. 【硬性必须】编辑 .env，替换以下两个占位值：
   SESSION_SECRET：至少 32 个随机字符；用于保护登录会话。
   ADMIN_PASSWORD：Web 管理员首次登录密码，建议至少 12 位。

   可生成随机 SESSION_SECRET：
   python3 -c "import secrets; print(secrets.token_hex(32))"

   不要提交 .env；项目已配置忽略它。

5. 如果已有旧版数据，【硬性必须】先备份整个 config 目录：
   cp -a config config.backup.before-fixed

6. 构建并启动：
   docker compose build --no-cache
   docker compose up -d

7. 查看启动日志：
   docker compose logs -f baidu-autosave

8. 浏览器打开：
   http://服务器地址:5000

   默认管理员用户名：admin
   密码：第 4 步写入 .env 的 ADMIN_PASSWORD

三、【硬性必须】旧配置迁移规则

1. 配置结构统一为 config_schema_version = 2。
2. 首次读取旧配置时会先做语义迁移；迁移前会在 config/backups 中保存备份。
3. 复杂 Cron 不会被错误改成固定时间，而是原样保存为 raw_cron。
4. 如果任务字段存在歧义、路径不安全或迁移后语义不合法，启动会停止迁移并保留原配置，不能跳过错误继续写入。
5. 不要手动删除 task_uid、rule_uid，也不要把任务运行状态写入 config.json。

四、新增功能操作方法

1. 分享文件浏览器
   打开“添加任务”后，文件浏览器始终显示在分享链接下方。
   输入链接并离开输入框时会自动加载，也可点击“加载/刷新”。
   可展开目录并勾选文件或文件夹。
   不勾选任何项目 = 保存全部；勾选后 = 只保存选中项目。
   编辑任务时会自动重新加载文件列表并恢复勾选。

2. 保存名称 save_name
   “保存路径”是父目录，“保存名称”是其下一级子目录。
   页面会实时显示最终保存位置。
   例如：保存路径 /我的资源/电影，保存名称 新剧集，最终为 /我的资源/电影/新剧集。
   保存名称只能是单个目录名，不能包含 /、反斜杠、.. 或控制字符。

3. 百度网盘目录树
   点击保存路径右侧“浏览”，读取当前账号的真实网盘目录。
   点击文件夹逐级进入；点击面包屑返回上级；点击“选择当前目录”确认。

4. 扁平化保存
   选择“扁平化保存”后，选中文件全部保存到最终目标目录，不创建分享中的多层目录。
   如果两个不同来源文件扁平化后同名，系统会在转存前报错并停止，避免静默覆盖。

5. 中文定时
   “使用全局定时”：继承系统默认 Cron。
   “简单定时”：可添加多个“星期 + 时间”组合，一个组合可多选星期。
   “不启用”：该任务不会被定时器调度，但仍可手动执行。
   页面显示自动生成的五段 Cron 预览；后端按各时间段创建稳定的 rule_uid 调度任务。

6. 超时与进度
   每个任务可设置 30～86400 秒超时，默认 1800 秒。
   使用 threading.Timer + threading.Event，不再调用 signal.alarm，因此可在 Flask、gevent 和普通子线程中运行。
   执行中的等待采用 Event.wait，可及时响应超时；百度 SDK 已经进入的单次阻塞网络调用只能在该调用返回后进入取消检查点。
   进度固定为四步：访问分享链接、扫描目标目录、生成转存计划、执行转存。

五、更新已有部署

1. 备份 config：
   cp -a config config.backup.before-update

2. 停止旧容器：
   docker compose down

3. 用本压缩包源码覆盖程序文件，但保留自己的 config 目录和 .env。

4. 重新构建，不能只执行 pull：
   docker compose build --no-cache
   docker compose up -d

5. 登录后检查：用户账号、任务数量、保存路径、勾选内容和定时时间段。

六、验证命令

后端单元测试：
python3 -m unittest discover -s tests -v

Python 语法检查：
python3 -m py_compile *.py

前端生产构建：
cd frontend
npm ci
npm run build

本次交付结果：14 项后端核心测试通过；全部 Python 文件编译通过；Vue/TypeScript 生产构建通过。
当前运行环境没有 Docker 命令，因此未在本机执行最终 Docker 镜像构建；Dockerfile、entrypoint 与 Compose 配置已做静态检查，其中 entrypoint 通过 sh -n。

七、故障恢复

1. 新配置无法启动：停止容器，将 config/backups 中最近的备份复制回 config/config.json。
2. config/config.json 权限异常：容器入口会修正属主并设为 600。
3. 文件树读取失败：检查百度账号 Cookie、分享链接有效期和提取码；不要把 Cookie 或提取码贴到公开日志。
4. 定时任务未运行：检查任务是否选择了“不启用”、星期/时间是否完整，以及容器 TZ 是否正确。
5. 扁平化同名冲突：取消扁平化、减少勾选范围，或先用重命名规则产生唯一文件名。

八、验证边界

本交付没有使用你的真实百度 Cookie，也没有对你的网盘进行真实转存、创建目录、重命名或删除操作，因此这些外部 API 行为需要你在测试目录先做一次小范围验收。任何软件都无法诚实承诺“绝对零 Bug”；本版本通过了可离线验证的核心逻辑、编译和生产构建，并对外部操作采用失败即停止、配置备份和扁平化冲突预检。