尧图网站建设 
TagStudio 图书馆系统详解库的创建、.TagStudio数据目录结构、目录刷新、备份与可移植性原理【免费下载链接】TagStudioA User-Focused Photo File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio本文基于 TagStudio 官方文档 docs/libraries.md 展开系统讲解图书馆Library这一核心抽象一个内容文件夹如何变成 TagStudio 可管理的库、库元数据条目、标签、字段、颜色存储在哪里、目录刷新扫描的实现原理ripgrep 与 wcmatch 双引擎、备份机制以及基于相对路径的库可移植性设计。读完本文你能完整掌握库的创建/打开流程、.TagStudio数据目录各文件的职责并能结合 src/tagstudio/core/library/ 下的源码理解其底层实现。1. 什么是 TagStudio 图书馆被动式、非破坏性的文件管理模型在 TagStudio 中一个图书馆Library 一个内容文件夹 该库专属的 TagStudio 数据。它代表一组内容照片、文档或任意其他受支持的文件类型参见 docs/preview-support.md并包含仅属于该库的标签tags、字段fields、颜色colors等数据以及这些数据与你文件之间的关联关系。理解 TagStudio 的库关键有三点被动式纳入Passive inclusionTagStudio 把所选文件夹包括子文件夹的内容包含进来作为文件条目file entries但只是登记引用并不接管文件的物理位置完全非破坏性你的文件永远不会被移动、复制或修改——这是官方文档中特别加粗强调的底线承诺位置无关库文件夹可以放在本地磁盘、外置硬盘、网络驱动器/NAS或任何你的系统能访问的位置。这个设计决定了后文的所有机制库的全部元数据都收敛在内容文件夹内的一个隐藏数据目录中且文件条目使用相对路径存储从而实现了整个文件夹拷走库也完好的可移植性。2. 创建 / 打开图书馆从菜单动作到数据库初始化2.1 操作入口创建或打开库的方式是菜单File → Open/Create Library或使用快捷键CtrlOmacOS 上为⌘ CommandO选择一个包含文件内容的文件夹作为 TagStudio 图书馆。行为逻辑是二选一的如果该目录内不存在.TagStudio数据文件夹 → TagStudio 会创建它并自动扫描文件夹把找到的文件加入库如果.TagStudio已存在 → 直接打开这个既有库。2.2 源码层面open_library的分发逻辑从 src/tagstudio/core/library/alchemy/library.py 中的Library.open_library()可以看到这一判断的精确实现sql_path library_dir / TS_FOLDER_NAME / SQL_FILENAME # .TagStudio/ts_library.sqlite json_path library_dir / TS_FOLDER_NAME / JSON_FILENAME # .TagStudio/ts_library.json is_new not sql_path.exists() if not in_memory: self.verify_ts_folder(library_dir) # ensure .TagStudio directory exists if is_new and json_path.exists(): return LibraryStatus(..., json_migration_reqTrue) # 需要 JSON - SQLite 迁移 if is_new: return self.create_sqlite_library(library_dir, in_memory) return self.open_sqlite_library(library_dir, in_memory)其中TS_FOLDER_NAME、SQL_FILENAME等常量分别在 src/tagstudio/core/constants.pyTS_FOLDER_NAME .TagStudio、BACKUP_FOLDER_NAME backups、IGNORE_NAME .ts_ignore、THUMB_CACHE_NAME thumbs与 src/tagstudio/core/library/alchemy/constants.pySQL_FILENAME ts_library.sqlite、JSON_FILENAME ts_library.json当前DB_VERSION 400中定义。QT 层的入口在 src/tagstudio/qt/qt_driver.py 的open_library()先调用lib.open_library(path)若返回json_migration_req则弹出 JSON 迁移向导见第 7 节否则进入_init_library()初始化界面、缩略图缓存CacheManager等。菜单动作本身的注册在 src/tagstudio/qt/controllers/main_window.py。2.3 新建库时数据库里预置了什么create_sqlite_library()src/tagstudio/core/library/alchemy/library.py#L406-L500在建立空库时一次性完成大量初始化工作建表通过 SQLAlchemyModelBase.metadata.create_all(conn)创建全部表entries、tags、tag_entries、tag_parents、tag_colors等保留 ID 段内置标签占用id02TAG_ARCHIVED0、TAG_FAVORITE1、TAG_META2见 src/tagstudio/core/constants.py#L32-L36并通过向sqlite_sequence插入临时行再删除的技巧把tags自增序列推到RESERVED_TAG_END(999) 之后保证用户新标签不会撞上保留 ID默认数据默认颜色命名空间与整套默认标签颜色standard、pastels、shades、grayscale、earth_tones、neon 六个分组三个默认标签Meta Tags分类、Archived隐藏、Favorite见get_default_tags()默认字段模板Title、Author、Artist、URL、Description(多行)、Notes(多行)、Comments(多行)、Date定义在 src/tagstudio/core/library/alchemy/constants.py#L42-L51版本记录versions表中写入INITIAL与CURRENT两行值均为当前DB_VERSION从模板生成默认.ts_ignore文件复制自resources/templates/ts_ignore_template.txt索引为tags(name, shorthand)、tag_parents(child_id)、tag_entries(entry_id)建立查询索引。值得注意的是数据库连接使用了NullPool连接池src/tagstudio/core/library/alchemy/library.py#L380-L404注释中解释了原因文件型 SQLite 使用NullPool可让各线程建立独立连接避免连接关闭后 DB 文件仍被锁住的问题。3..TagStudio数据目录结构与职责创建库时TagStudio 会在所选内容文件夹的根目录下创建隐藏的.TagStudio文件夹即数据文件夹data folder。它保存该库的全部 TagStudio 数据哪些文件被纳入库、你创建了哪些标签、哪些文件打了哪些标签等等。这也意味着标签是按库per-library存在的——跨库共享的全局标签目前还在 Roadmap 计划中。3.1 数据目录内部结构文件/文件夹说明ts_library.sqlite库的保存文件。存储所有条目entries、标签tags、字段fields及其他元数据。(v9.5.0).ts_ignore可选的忽略文件用于在库扫描时排除特定文件与文件夹语法类似.gitignore。backups/库保存文件的时间戳备份。thumbs/文件预览所用的缩略图缓存。一个典型的库文件夹长这样My Library/ # (内容文件夹) ├─ file_1.jpg ├─ file_2.txt ├─ .TagStudio/ # (数据文件夹) │ ├─ ts_library.sqlite (引用外部文件夹中的文件) │ ├─ .ts_ignore │ ├─ backups/ │ ├─ thumbs/3.2 扫描中还有两个隐形文件从源码结构看数据目录在运行期还会出现另外两个文件.compiled_ignore目录刷新时src/tagstudio/core/library/refresh.py 会把内置 用户的忽略模式临时写入.TagStudio/.compiled_ignore作为--ignore-file传给 ripgrep用完即删collages/src/tagstudio/core/constants.py#L21 中定义了COLLAGE_FOLDER_NAME collages用于拼贴预览缓存。.ts_ignore的完整语法注释、目录匹配、!取反、*/?/**通配符、字符集等有独立文档详见 docs/ignore.md本文不再展开。4. 目录刷新Refreshing Directories默认扫描与双引擎实现4.1 默认行为与设置开关TagStudio默认在打开库时自动扫描新增或更新的文件。如果库非常大或位于慢速驱动器上可以在设置中关闭这一行为Settings → Automatically Load New Files手动刷新的入口是菜单File → Refresh Directories快捷键CtrlRmacOS 上为⌘ CommandR。菜单项注册于 src/tagstudio/qt/controllers/main_window.py#L155-L165。从源码确认默认扫描开关src/tagstudio/qt/qt_driver.py#L1678-L1679 中_init_library()打开库后判断if self.settings.scan_files_on_open: self.add_new_files_callback()即打开即扫描由scan_files_on_open设置项控制与文档描述一一对应。4.2 刷新流程扫描 → 进度反馈 → 批量入库刷新动作在 QT 驱动层由add_new_files_callback()src/tagstudio/qt/qt_driver.py#L1069-L1105启动创建RefreshTracker在QThreadPool工作线程中跑tracker.refresh_dir(library_dir)UI 线程通过信号接收进度已扫描 N 个文件 / 发现 M 个新文件扫描完成后add_new_files_runnable()执行tracker.save_new_files()把新文件写入数据库。RefreshTracker的实现src/tagstudio/core/library/refresh.py有几个值得注意的细节双引擎扫描优先检测系统上是否安装了 ripgrepshutil.which(rg)有 ripgrep执行rg --files --follow --hidden --ignore-file .compiled_ignore在库目录内运行一次性拿到全部文件列表性能更好且模式匹配与.gitignore完全一致没有 ripgrep回退到内置的wcmatch库用glob(***/*, excludeignore_patterns)遍历。官方 docs/ignore.md 也指出两种工具在边缘情况下可能存在细微不一致ripgrep 是首选方案增量去重扫描到的每个文件先查self.library.included_files内存中已知文件集合与has_entry_with_path()数据库中存在性检查只有真正的新文件才会进入files_not_in_library待写入列表批量写入save_new_files()以batch_size 200为一批构造Entry(path..., fields[], date_addednow())并调用library.add_entries(entries)边写边向 UI 让渡进度忽略规则只在扫描期生效.ts_ignore只影响扫描新文件这一步对已入库的文件不生效这一点在 docs/ignore.md 中有明确说明。5. 图书馆信息面板Library Information PanelTools → Library Information可以打开图书馆信息面板见文首截图其中包含库的各类统计信息以及常见库维护任务的快速入口例如Relink重新链接条目修复指向缺失文件的条目Ignored files忽略文件管理处理被.ts_ignore命中的已入库文件库数据备份管理查看/管理backups/中的备份文件。面板对应 src/tagstudio/qt/controllers/library_info_window.py其维护能力在库打开后由驱动层逐项启用src/tagstudio/qt/qt_driver.py#L1699-L1709 中可看到fix_unlinked_entries_action、fix_ignored_entries_action、fix_dupe_files_action等动作在库就绪后才被启用。6. 保存与备份自动保存 时间戳备份6.1 自动保存自v9.5.0起库在你操作过程中自动保存无需手动 CtrlS。6.2 手动创建时间戳备份菜单入口File → Save Library Backup快捷键CtrlShiftSmacOS 上为⌘ CommandShiftS触发时机除手动之外每当数据库文件被迁移到更新版本时也会自动创建一个备份作为预防措施。6.3 备份的精确内容与命名规则备份目前只包含ts_library.sqlite文件——因为核心 TagStudio 数据都在这个数据库文件里。你自己的文件不属于任何备份。备份存放于库数据文件夹的.TagStudio/backups/下可再从Tools → Library Information面板中管理。源码中save_library_backup_to_disk()src/tagstudio/core/library/alchemy/library.py#L1448-L1464给出了备份文件的精确命名规则filename fts_library_backup_{datetime.now(UTC).strftime(%Y_%m_%d_%H%M%S)}.sqlite target_path library_dir / TS_FOLDER_NAME / BACKUP_FOLDER_NAME / filename shutil.copy2(library_dir / TS_FOLDER_NAME / SQL_FILENAME, target_path)即文件名形如ts_library_backup_2025_03_03_153000.sqlite时间为 UTC通过shutil.copy2直接拷贝当前数据库文件保留元数据。而迁移前自动备份这一点可在open_sqlite_library()中验证src/tagstudio/core/library/alchemy/library.py#L502-L518migrations DBMigrations(library_dir, self.engine) # save backup if patches will be applied if migrations.required: Library.save_library_backup_to_disk(library_dir) migrations.run()7. 遗留库迁移Legacy Library Migration7.1 JSON → SQLitev9.4.2 及更早 → v9.5.0如果你用v9.5.0 或更新版本打开一个由TagStudio v9.4.2 或更早创建的库会进入迁移向导流程把旧的ts_library.json存档转换为新的ts_library.sqlite格式。原始 JSON 文件会被保留等你确认迁移无误后可以从View → Library Information面板中将其删除。实现链路是open_library()检测到无ts_library.sqlite但有ts_library.json时返回json_migration_reqTrue→ QT 层弹出JsonMigrationModalsrc/tagstudio/qt/mixed/migration_modal.py→ 用户确认后由Library.migrate_json_to_sqlite()src/tagstudio/core/library/alchemy/library.py#L231-L336完成数据搬迁标签及其颜色、别名、父标签关系、条目与字段旧版Tags字段直接转成真正的标签见LEGACY_TAG_FIELD_IDS {6, 7, 8}同时把旧的扩展名黑白名单转换为.ts_ignore文件migrate_ext_list。相关测试可参考 tests/core/library/test_json_migration.py。7.2 SQLite 数据库的版本化迁移ts_library.sqlite自身也有一套增量迁移机制src/tagstudio/core/library/alchemy/migrations.py版本记录在versions表CURRENT/INITIAL两个键当前仓库DB_VERSION 400兼容策略版本号 ≥ 100 时视为主.次复合版本——主版本version // 100高于程序支持的版本则拒绝加载避免破坏性不兼容仅次版本更新则允许加载迁移链MigrationTo7 → 8 → 9 → 100 → 101 → 102 → 103 → 104 → 200 → 201 → 202 → 300 → 400每步一个独立类修标签引用、加列、建表、重建字段表、删除废弃的folders表、新增category_exclusions表等每完成一步即写入新的CURRENT版本并提交任何错误都会回滚事务每次迁移前都有第 6.3 节所述的自动备份兜底。测试夹具中的各历史版本空库tests/fixtures/empty_libraries/如DB_VERSION_100、DB_VERSION_6等目录与 tests/core/library/test_migrations.py 正是用于逐版本验证这条迁移链。8. 库的可移植性Library Portability这是.TagStudio目录设计带来的一个直接红利数据文件夹位于内容文件夹内部与内容同生同死库中所有文件条目路径都是相对于内容文件夹存储的entries.path是相对路径SQLite 中注释也写明 References outer folder for files。因此整个库文件夹可以自由移动到其他位置而不会产生脱链unlinked条目外置硬盘上的库可以随意插到不同电脑上打开库放在网络驱动器或 NAS 上时多台电脑即使映射的网络位置不同也能各自正常访问。适用前提与限制官方文档明确说明TagStudio 目前不支持多个用户同时访问同一个库——在网络/NAS 场景下这一点尤其重要多机共享时请串行使用。9. 计划中的库功能与变更Planned Library Featuresdocs/libraries.md 还列出了路线图详见 docs/roadmap.md中已规划的库相关方向理解它们有助于把握数据目录设计的演进选项把库数据与库内容分开存储使得可以为只读文件夹创建 TagStudio 库当前数据目录必须能写进内容文件夹使得可以对同一内容文件夹维护不同的库多根Multi-root库一个库可读多个内容文件夹降低对复杂 .ts_ignore 规则的依赖让库内容跨不同驱动器尤其是 Windows而不必依赖符号链接这类依赖操作系统的变通手段可共享的标签包与颜色包全局标签Global tags跨不同库可访问。10. 小结主题要点源码/文档依据库的本质内容文件夹 专属元数据文件永不被移动/复制/修改docs/libraries.md创建/打开File → Open/Create LibraryCtrlO无.TagStudio则新建并扫描library.pyopen_library数据目录ts_library.sqlite/.ts_ignore/backups//thumbs/core/constants.py目录刷新打开时默认扫描scan_files_on_open可关CtrlR 手动ripgrep 优先、wcmatch 兜底refresh.py、qt_driver.py备份自动保存CtrlShiftS 手动备份仅含 sqlite迁移前自动备份library.py迁移JSON→SQLite 向导保留原 JSONSQLite 内部按 7→400 迁移链升级并自动备份migrations.py、test_migrations.py可移植性条目路径相对内容文件夹整库可整体迁移不支持多用户并发访问docs/libraries.md掌握以上内容后你既能按标准流程管理日常库创建、扫描、备份、维护也能在需要排查问题时准确定位到.TagStudio目录中的对应文件与源码模块。【免费下载链接】TagStudioA User-Focused Photo File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TagStudio 图书馆系统详解：库的创建、`.TagStudio` 数据目录结构、目录刷新、备份与可移植性原理
TagStudio 图书馆系统详解库的创建、.TagStudio数据目录结构、目录刷新、备份与可移植性原理【免费下载链接】TagStudioA User-Focused Photo File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio本文基于 TagStudio 官方文档 docs/libraries.md 展开系统讲解图书馆Library这一核心抽象一个内容文件夹如何变成 TagStudio 可管理的库、库元数据条目、标签、字段、颜色存储在哪里、目录刷新扫描的实现原理ripgrep 与 wcmatch 双引擎、备份机制以及基于相对路径的库可移植性设计。读完本文你能完整掌握库的创建/打开流程、.TagStudio数据目录各文件的职责并能结合 src/tagstudio/core/library/ 下的源码理解其底层实现。1. 什么是 TagStudio 图书馆被动式、非破坏性的文件管理模型在 TagStudio 中一个图书馆Library 一个内容文件夹 该库专属的 TagStudio 数据。它代表一组内容照片、文档或任意其他受支持的文件类型参见 docs/preview-support.md并包含仅属于该库的标签tags、字段fields、颜色colors等数据以及这些数据与你文件之间的关联关系。理解 TagStudio 的库关键有三点被动式纳入Passive inclusionTagStudio 把所选文件夹包括子文件夹的内容包含进来作为文件条目file entries但只是登记引用并不接管文件的物理位置完全非破坏性你的文件永远不会被移动、复制或修改——这是官方文档中特别加粗强调的底线承诺位置无关库文件夹可以放在本地磁盘、外置硬盘、网络驱动器/NAS或任何你的系统能访问的位置。这个设计决定了后文的所有机制库的全部元数据都收敛在内容文件夹内的一个隐藏数据目录中且文件条目使用相对路径存储从而实现了整个文件夹拷走库也完好的可移植性。2. 创建 / 打开图书馆从菜单动作到数据库初始化2.1 操作入口创建或打开库的方式是菜单File → Open/Create Library或使用快捷键CtrlOmacOS 上为⌘ CommandO选择一个包含文件内容的文件夹作为 TagStudio 图书馆。行为逻辑是二选一的如果该目录内不存在.TagStudio数据文件夹 → TagStudio 会创建它并自动扫描文件夹把找到的文件加入库如果.TagStudio已存在 → 直接打开这个既有库。2.2 源码层面open_library的分发逻辑从 src/tagstudio/core/library/alchemy/library.py 中的Library.open_library()可以看到这一判断的精确实现sql_path library_dir / TS_FOLDER_NAME / SQL_FILENAME # .TagStudio/ts_library.sqlite json_path library_dir / TS_FOLDER_NAME / JSON_FILENAME # .TagStudio/ts_library.json is_new not sql_path.exists() if not in_memory: self.verify_ts_folder(library_dir) # ensure .TagStudio directory exists if is_new and json_path.exists(): return LibraryStatus(..., json_migration_reqTrue) # 需要 JSON - SQLite 迁移 if is_new: return self.create_sqlite_library(library_dir, in_memory) return self.open_sqlite_library(library_dir, in_memory)其中TS_FOLDER_NAME、SQL_FILENAME等常量分别在 src/tagstudio/core/constants.pyTS_FOLDER_NAME .TagStudio、BACKUP_FOLDER_NAME backups、IGNORE_NAME .ts_ignore、THUMB_CACHE_NAME thumbs与 src/tagstudio/core/library/alchemy/constants.pySQL_FILENAME ts_library.sqlite、JSON_FILENAME ts_library.json当前DB_VERSION 400中定义。QT 层的入口在 src/tagstudio/qt/qt_driver.py 的open_library()先调用lib.open_library(path)若返回json_migration_req则弹出 JSON 迁移向导见第 7 节否则进入_init_library()初始化界面、缩略图缓存CacheManager等。菜单动作本身的注册在 src/tagstudio/qt/controllers/main_window.py。2.3 新建库时数据库里预置了什么create_sqlite_library()src/tagstudio/core/library/alchemy/library.py#L406-L500在建立空库时一次性完成大量初始化工作建表通过 SQLAlchemyModelBase.metadata.create_all(conn)创建全部表entries、tags、tag_entries、tag_parents、tag_colors等保留 ID 段内置标签占用id02TAG_ARCHIVED0、TAG_FAVORITE1、TAG_META2见 src/tagstudio/core/constants.py#L32-L36并通过向sqlite_sequence插入临时行再删除的技巧把tags自增序列推到RESERVED_TAG_END(999) 之后保证用户新标签不会撞上保留 ID默认数据默认颜色命名空间与整套默认标签颜色standard、pastels、shades、grayscale、earth_tones、neon 六个分组三个默认标签Meta Tags分类、Archived隐藏、Favorite见get_default_tags()默认字段模板Title、Author、Artist、URL、Description(多行)、Notes(多行)、Comments(多行)、Date定义在 src/tagstudio/core/library/alchemy/constants.py#L42-L51版本记录versions表中写入INITIAL与CURRENT两行值均为当前DB_VERSION从模板生成默认.ts_ignore文件复制自resources/templates/ts_ignore_template.txt索引为tags(name, shorthand)、tag_parents(child_id)、tag_entries(entry_id)建立查询索引。值得注意的是数据库连接使用了NullPool连接池src/tagstudio/core/library/alchemy/library.py#L380-L404注释中解释了原因文件型 SQLite 使用NullPool可让各线程建立独立连接避免连接关闭后 DB 文件仍被锁住的问题。3..TagStudio数据目录结构与职责创建库时TagStudio 会在所选内容文件夹的根目录下创建隐藏的.TagStudio文件夹即数据文件夹data folder。它保存该库的全部 TagStudio 数据哪些文件被纳入库、你创建了哪些标签、哪些文件打了哪些标签等等。这也意味着标签是按库per-library存在的——跨库共享的全局标签目前还在 Roadmap 计划中。3.1 数据目录内部结构文件/文件夹说明ts_library.sqlite库的保存文件。存储所有条目entries、标签tags、字段fields及其他元数据。(v9.5.0).ts_ignore可选的忽略文件用于在库扫描时排除特定文件与文件夹语法类似.gitignore。backups/库保存文件的时间戳备份。thumbs/文件预览所用的缩略图缓存。一个典型的库文件夹长这样My Library/ # (内容文件夹) ├─ file_1.jpg ├─ file_2.txt ├─ .TagStudio/ # (数据文件夹) │ ├─ ts_library.sqlite (引用外部文件夹中的文件) │ ├─ .ts_ignore │ ├─ backups/ │ ├─ thumbs/3.2 扫描中还有两个隐形文件从源码结构看数据目录在运行期还会出现另外两个文件.compiled_ignore目录刷新时src/tagstudio/core/library/refresh.py 会把内置 用户的忽略模式临时写入.TagStudio/.compiled_ignore作为--ignore-file传给 ripgrep用完即删collages/src/tagstudio/core/constants.py#L21 中定义了COLLAGE_FOLDER_NAME collages用于拼贴预览缓存。.ts_ignore的完整语法注释、目录匹配、!取反、*/?/**通配符、字符集等有独立文档详见 docs/ignore.md本文不再展开。4. 目录刷新Refreshing Directories默认扫描与双引擎实现4.1 默认行为与设置开关TagStudio默认在打开库时自动扫描新增或更新的文件。如果库非常大或位于慢速驱动器上可以在设置中关闭这一行为Settings → Automatically Load New Files手动刷新的入口是菜单File → Refresh Directories快捷键CtrlRmacOS 上为⌘ CommandR。菜单项注册于 src/tagstudio/qt/controllers/main_window.py#L155-L165。从源码确认默认扫描开关src/tagstudio/qt/qt_driver.py#L1678-L1679 中_init_library()打开库后判断if self.settings.scan_files_on_open: self.add_new_files_callback()即打开即扫描由scan_files_on_open设置项控制与文档描述一一对应。4.2 刷新流程扫描 → 进度反馈 → 批量入库刷新动作在 QT 驱动层由add_new_files_callback()src/tagstudio/qt/qt_driver.py#L1069-L1105启动创建RefreshTracker在QThreadPool工作线程中跑tracker.refresh_dir(library_dir)UI 线程通过信号接收进度已扫描 N 个文件 / 发现 M 个新文件扫描完成后add_new_files_runnable()执行tracker.save_new_files()把新文件写入数据库。RefreshTracker的实现src/tagstudio/core/library/refresh.py有几个值得注意的细节双引擎扫描优先检测系统上是否安装了 ripgrepshutil.which(rg)有 ripgrep执行rg --files --follow --hidden --ignore-file .compiled_ignore在库目录内运行一次性拿到全部文件列表性能更好且模式匹配与.gitignore完全一致没有 ripgrep回退到内置的wcmatch库用glob(***/*, excludeignore_patterns)遍历。官方 docs/ignore.md 也指出两种工具在边缘情况下可能存在细微不一致ripgrep 是首选方案增量去重扫描到的每个文件先查self.library.included_files内存中已知文件集合与has_entry_with_path()数据库中存在性检查只有真正的新文件才会进入files_not_in_library待写入列表批量写入save_new_files()以batch_size 200为一批构造Entry(path..., fields[], date_addednow())并调用library.add_entries(entries)边写边向 UI 让渡进度忽略规则只在扫描期生效.ts_ignore只影响扫描新文件这一步对已入库的文件不生效这一点在 docs/ignore.md 中有明确说明。5. 图书馆信息面板Library Information PanelTools → Library Information可以打开图书馆信息面板见文首截图其中包含库的各类统计信息以及常见库维护任务的快速入口例如Relink重新链接条目修复指向缺失文件的条目Ignored files忽略文件管理处理被.ts_ignore命中的已入库文件库数据备份管理查看/管理backups/中的备份文件。面板对应 src/tagstudio/qt/controllers/library_info_window.py其维护能力在库打开后由驱动层逐项启用src/tagstudio/qt/qt_driver.py#L1699-L1709 中可看到fix_unlinked_entries_action、fix_ignored_entries_action、fix_dupe_files_action等动作在库就绪后才被启用。6. 保存与备份自动保存 时间戳备份6.1 自动保存自v9.5.0起库在你操作过程中自动保存无需手动 CtrlS。6.2 手动创建时间戳备份菜单入口File → Save Library Backup快捷键CtrlShiftSmacOS 上为⌘ CommandShiftS触发时机除手动之外每当数据库文件被迁移到更新版本时也会自动创建一个备份作为预防措施。6.3 备份的精确内容与命名规则备份目前只包含ts_library.sqlite文件——因为核心 TagStudio 数据都在这个数据库文件里。你自己的文件不属于任何备份。备份存放于库数据文件夹的.TagStudio/backups/下可再从Tools → Library Information面板中管理。源码中save_library_backup_to_disk()src/tagstudio/core/library/alchemy/library.py#L1448-L1464给出了备份文件的精确命名规则filename fts_library_backup_{datetime.now(UTC).strftime(%Y_%m_%d_%H%M%S)}.sqlite target_path library_dir / TS_FOLDER_NAME / BACKUP_FOLDER_NAME / filename shutil.copy2(library_dir / TS_FOLDER_NAME / SQL_FILENAME, target_path)即文件名形如ts_library_backup_2025_03_03_153000.sqlite时间为 UTC通过shutil.copy2直接拷贝当前数据库文件保留元数据。而迁移前自动备份这一点可在open_sqlite_library()中验证src/tagstudio/core/library/alchemy/library.py#L502-L518migrations DBMigrations(library_dir, self.engine) # save backup if patches will be applied if migrations.required: Library.save_library_backup_to_disk(library_dir) migrations.run()7. 遗留库迁移Legacy Library Migration7.1 JSON → SQLitev9.4.2 及更早 → v9.5.0如果你用v9.5.0 或更新版本打开一个由TagStudio v9.4.2 或更早创建的库会进入迁移向导流程把旧的ts_library.json存档转换为新的ts_library.sqlite格式。原始 JSON 文件会被保留等你确认迁移无误后可以从View → Library Information面板中将其删除。实现链路是open_library()检测到无ts_library.sqlite但有ts_library.json时返回json_migration_reqTrue→ QT 层弹出JsonMigrationModalsrc/tagstudio/qt/mixed/migration_modal.py→ 用户确认后由Library.migrate_json_to_sqlite()src/tagstudio/core/library/alchemy/library.py#L231-L336完成数据搬迁标签及其颜色、别名、父标签关系、条目与字段旧版Tags字段直接转成真正的标签见LEGACY_TAG_FIELD_IDS {6, 7, 8}同时把旧的扩展名黑白名单转换为.ts_ignore文件migrate_ext_list。相关测试可参考 tests/core/library/test_json_migration.py。7.2 SQLite 数据库的版本化迁移ts_library.sqlite自身也有一套增量迁移机制src/tagstudio/core/library/alchemy/migrations.py版本记录在versions表CURRENT/INITIAL两个键当前仓库DB_VERSION 400兼容策略版本号 ≥ 100 时视为主.次复合版本——主版本version // 100高于程序支持的版本则拒绝加载避免破坏性不兼容仅次版本更新则允许加载迁移链MigrationTo7 → 8 → 9 → 100 → 101 → 102 → 103 → 104 → 200 → 201 → 202 → 300 → 400每步一个独立类修标签引用、加列、建表、重建字段表、删除废弃的folders表、新增category_exclusions表等每完成一步即写入新的CURRENT版本并提交任何错误都会回滚事务每次迁移前都有第 6.3 节所述的自动备份兜底。测试夹具中的各历史版本空库tests/fixtures/empty_libraries/如DB_VERSION_100、DB_VERSION_6等目录与 tests/core/library/test_migrations.py 正是用于逐版本验证这条迁移链。8. 库的可移植性Library Portability这是.TagStudio目录设计带来的一个直接红利数据文件夹位于内容文件夹内部与内容同生同死库中所有文件条目路径都是相对于内容文件夹存储的entries.path是相对路径SQLite 中注释也写明 References outer folder for files。因此整个库文件夹可以自由移动到其他位置而不会产生脱链unlinked条目外置硬盘上的库可以随意插到不同电脑上打开库放在网络驱动器或 NAS 上时多台电脑即使映射的网络位置不同也能各自正常访问。适用前提与限制官方文档明确说明TagStudio 目前不支持多个用户同时访问同一个库——在网络/NAS 场景下这一点尤其重要多机共享时请串行使用。9. 计划中的库功能与变更Planned Library Featuresdocs/libraries.md 还列出了路线图详见 docs/roadmap.md中已规划的库相关方向理解它们有助于把握数据目录设计的演进选项把库数据与库内容分开存储使得可以为只读文件夹创建 TagStudio 库当前数据目录必须能写进内容文件夹使得可以对同一内容文件夹维护不同的库多根Multi-root库一个库可读多个内容文件夹降低对复杂 .ts_ignore 规则的依赖让库内容跨不同驱动器尤其是 Windows而不必依赖符号链接这类依赖操作系统的变通手段可共享的标签包与颜色包全局标签Global tags跨不同库可访问。10. 小结主题要点源码/文档依据库的本质内容文件夹 专属元数据文件永不被移动/复制/修改docs/libraries.md创建/打开File → Open/Create LibraryCtrlO无.TagStudio则新建并扫描library.pyopen_library数据目录ts_library.sqlite/.ts_ignore/backups//thumbs/core/constants.py目录刷新打开时默认扫描scan_files_on_open可关CtrlR 手动ripgrep 优先、wcmatch 兜底refresh.py、qt_driver.py备份自动保存CtrlShiftS 手动备份仅含 sqlite迁移前自动备份library.py迁移JSON→SQLite 向导保留原 JSONSQLite 内部按 7→400 迁移链升级并自动备份migrations.py、test_migrations.py可移植性条目路径相对内容文件夹整库可整体迁移不支持多用户并发访问docs/libraries.md掌握以上内容后你既能按标准流程管理日常库创建、扫描、备份、维护也能在需要排查问题时准确定位到.TagStudio目录中的对应文件与源码模块。【免费下载链接】TagStudioA User-Focused Photo File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考