如何从0到1完成TeamPass二次开发自定义模块实战与避坑指南【免费下载链接】TeamPassCollaborative Passwords Manager项目地址: https://gitcode.com/gh_mirrors/te/TeamPass接手团队一套 TeamPass 密码管理器后你大概率会遇到这样的场景功能够用但差一点——想给密码条目加一个所属项目编号字段、想在内网系统里调用密码数据、想把新员工入职流程自动化。改吧不知道从哪里下手不改吧每天手工复制粘贴。这篇文章就围绕TeamPass二次开发展开带你走完分析入口 → 最小改动 → 验证效果 → 避开坑的完整闭环读完你就能亲手交付第一个自定义模块。为什么TeamPass值得二次开发先看清它的运转逻辑 二次开发最大的障碍不是改代码而是不知道改哪里。TeamPass 是 PHP 8.2 的协作密码管理器架构上并不复杂把它拆成三条主线就能看懂请求链路浏览器/API 请求 → 入口路由app/api/index.php或public/index.php→sources/下的业务查询文件 → 数据库。数据底座所有系统设置存在teampass_misc表type分组、intitule键名、valeur值由 ConfigManager 统一加载成$SETTINGS数组密码条目、文件夹、自定义字段分别在各自的业务表中。扩展入口前端页面在app/pages/配套 JS 逻辑在app/pages/*.js.php后端逻辑在app/sources/*.queries.php类库在app/includes/libraries/teampassclasses/。理解设置都走$SETTINGS、业务都走sources/、类库都走teampassclasses/这三句话你就抓住了整个扩展开发的核心入口。新增功能时只需沿着这三条线打补丁无需理解全项目。第一个实战给密码条目加一个自定义字段 目标很明确在添加/编辑条目页面多一个项目编号输入框并让它随条目一起存取。这是最典型的自定义模块实战改动量小、见效快。第1步确认功能开关自定义字段依赖管理页开启的item_extra_fields设置。在管理后台选项里确认已开启随后检查数据库结构// 自定义字段的定义存在 teampass_categories 表 // 每个条目上的值存在 teampass_items_fields 表 DB::query(SELECT * FROM . prefixTable(categories) . ORDER BY order ASC);第2步在 fields.queries.php 里注册新字段app/sources/fields.queries.php是字段管理的后端找到保存新字段的 action追加一个类型分支即可// 保存自定义字段定义text / password / date / select 等 DB::insert(prefixTable(categories), [ title $request-request-get(field_title), // 字段显示名 type $request-request-get(field_type), // 字段类型 order $nextOrder, // 展示顺序 ]);第3步在条目表单中渲染并保存app/pages/items.php的表单区遍历categories输出输入框保存时把值写入items_fields。关键在于值的加密要复用系统机制而不是自己发明——TeamPass 的条目字段默认走加密存储自定义字段也不例外// 保存条目时加密自定义字段值 $encryptedValue cryption($fieldValue, $SETTINGS, encrypt)[string]; DB::insert(prefixTable(items_fields), [ item_id $newItemId, field_id $fieldId, value $encryptedValue, ]);第4步验证添加一条带项目编号的条目 → 编辑回显是否正常 → 用 API 或导出功能确认字段随条目一起输出。三个点都通第一个自定义模块就算交付了。进阶技巧三招提升扩展效率 ⚡完成了最小改动下面这三个技巧能让你的二次开发从能用走向好用。技巧1自定义设置项两行代码搞定很多定制需求只是多一个可配置开关。设置项本质上就是teampass_misc表的一行新增一个设置项只需两段代码// 写入管理页面 action 中 DB::insert(prefixTable(misc), [ type my_module, // 分组标识 intitule my_custom_setting, // 设置键名 valeur $postedValue, ]); // 读取任何业务文件中 $SETTINGS (new ConfigManager())-getAllSettings(); $value $SETTINGS[my_custom_setting] ?? default;读取设置的核心类在app/includes/libraries/teampassclasses/configmanager/src/ConfigManager.php这是所有页面、API、后台任务统一取设置的入口。技巧2通过REST API暴露自定义数据如果希望外部系统能读取你的扩展数据直接复用现成的 API 链路是最省力的方式。路由在app/api/index.php控制器在app/api/Controller/Api/新增一个 controller 分支 一个 Action 方法即可JWT 鉴权、速率限制、网络 ACL 全部自动生效无需重复实现安全层// app/api/index.php 路由区新增 } elseif ($controller misc) { require API_ROOT_PATH . /Controller/Api/MiscController.php; $objFeedController new MiscController(); $strMethodName $action . Action; $objFeedController-{$strMethodName}(); }完整的接口契约OpenAPI 3.1 规范在app/api/openapi.json这是你对接前最好的参考书。技巧3让后台任务帮你悄悄干活密码轮换、过期提醒、日志清理这类周期任务TeamPass 有现成的调度框架app/scripts/下的 background tasks 系列。把耗时逻辑写成独立脚本再注册到调度器就能避免阻塞页面请求。避坑指南二次开发最常见的五个坑 ⚠️坑1改了设置不生效原因$SETTINGS是按请求加载的而部分环境开了配置缓存。解决改完设置先清缓存、再刷新页面若仍不生效检查teampass_misc表是否插入了重复行intitule冲突这是新增设置项时最容易踩的雷。坑2自己写了一套加密逻辑原因想当然地认为存个密码用 base64 就行。解决TeamPass 采用多层加密用户盐密钥 服务器密钥数据损坏后几乎不可逆。务必复用cryption()或 CryptManager 类永远不要绕过现有加密机制。项目里有app/scripts/_local/scan_corrupted_items.php等诊断脚本正是因为历史上有过损坏案例。坑3版本升级后扩展代码报错原因TeamPass 每代大版本会调整内部 API如 3.0 升级 phpseclib、3.1 重构用户-角色表。解决升级前看docs/install/upgrade.md和根目录的migrate_3.2.x.php迁移脚本升级后用tests/目录下的 PHPUnit 套件回归你的扩展点。坑4改前端 JS 不生效原因app/pages/*.js.php是后端动态输出的脚本浏览器缓存了旧版本。解决改完js.php记得强制刷新CtrlF5或改app/config/include.php中与版本相关的常量让静态资源 URL 变化从而绕过缓存。坑5API 报 403/429排查没头绪原因403 多半是 CORS 白名单或网络 ACL 限制429 是内置速率限制在起作用。解决在管理后台的 API 设置里检查api_cors_origins与api_rate_limit_per_minute新装环境默认开启 HTTPS 强制非 HTTPS 请求一律 403。从哪里继续给你的行动路线图 官方文档docs/install/installation.md环境搭建、docs/api/api-basic.mdAPI 基础核心源码配置加载app/includes/libraries/teampassclasses/configmanager/、字段管理app/sources/fields.queries.php、API 路由app/api/index.php、后台任务app/scripts/测试参考tests/目录是现成的示例代码库里面每个单测都在演示如何安全地调用项目内部 API比任何文档都直观二次开发的秘诀就一句话找最小的入口做最小的改动用系统的机制解决系统的问题。现在你已经知道了入口在哪里、怎么验证、有哪些坑不妨就从今天开始给 TeamPass 加上你团队真正需要的那个功能吧。愿你的第一次 TeamPass二次开发成为之后一系列定制化模块的起点。✨【免费下载链接】TeamPassCollaborative Passwords Manager项目地址: https://gitcode.com/gh_mirrors/te/TeamPass创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何从0到1完成TeamPass二次开发：自定义模块实战与避坑指南
如何从0到1完成TeamPass二次开发自定义模块实战与避坑指南【免费下载链接】TeamPassCollaborative Passwords Manager项目地址: https://gitcode.com/gh_mirrors/te/TeamPass接手团队一套 TeamPass 密码管理器后你大概率会遇到这样的场景功能够用但差一点——想给密码条目加一个所属项目编号字段、想在内网系统里调用密码数据、想把新员工入职流程自动化。改吧不知道从哪里下手不改吧每天手工复制粘贴。这篇文章就围绕TeamPass二次开发展开带你走完分析入口 → 最小改动 → 验证效果 → 避开坑的完整闭环读完你就能亲手交付第一个自定义模块。为什么TeamPass值得二次开发先看清它的运转逻辑 二次开发最大的障碍不是改代码而是不知道改哪里。TeamPass 是 PHP 8.2 的协作密码管理器架构上并不复杂把它拆成三条主线就能看懂请求链路浏览器/API 请求 → 入口路由app/api/index.php或public/index.php→sources/下的业务查询文件 → 数据库。数据底座所有系统设置存在teampass_misc表type分组、intitule键名、valeur值由 ConfigManager 统一加载成$SETTINGS数组密码条目、文件夹、自定义字段分别在各自的业务表中。扩展入口前端页面在app/pages/配套 JS 逻辑在app/pages/*.js.php后端逻辑在app/sources/*.queries.php类库在app/includes/libraries/teampassclasses/。理解设置都走$SETTINGS、业务都走sources/、类库都走teampassclasses/这三句话你就抓住了整个扩展开发的核心入口。新增功能时只需沿着这三条线打补丁无需理解全项目。第一个实战给密码条目加一个自定义字段 目标很明确在添加/编辑条目页面多一个项目编号输入框并让它随条目一起存取。这是最典型的自定义模块实战改动量小、见效快。第1步确认功能开关自定义字段依赖管理页开启的item_extra_fields设置。在管理后台选项里确认已开启随后检查数据库结构// 自定义字段的定义存在 teampass_categories 表 // 每个条目上的值存在 teampass_items_fields 表 DB::query(SELECT * FROM . prefixTable(categories) . ORDER BY order ASC);第2步在 fields.queries.php 里注册新字段app/sources/fields.queries.php是字段管理的后端找到保存新字段的 action追加一个类型分支即可// 保存自定义字段定义text / password / date / select 等 DB::insert(prefixTable(categories), [ title $request-request-get(field_title), // 字段显示名 type $request-request-get(field_type), // 字段类型 order $nextOrder, // 展示顺序 ]);第3步在条目表单中渲染并保存app/pages/items.php的表单区遍历categories输出输入框保存时把值写入items_fields。关键在于值的加密要复用系统机制而不是自己发明——TeamPass 的条目字段默认走加密存储自定义字段也不例外// 保存条目时加密自定义字段值 $encryptedValue cryption($fieldValue, $SETTINGS, encrypt)[string]; DB::insert(prefixTable(items_fields), [ item_id $newItemId, field_id $fieldId, value $encryptedValue, ]);第4步验证添加一条带项目编号的条目 → 编辑回显是否正常 → 用 API 或导出功能确认字段随条目一起输出。三个点都通第一个自定义模块就算交付了。进阶技巧三招提升扩展效率 ⚡完成了最小改动下面这三个技巧能让你的二次开发从能用走向好用。技巧1自定义设置项两行代码搞定很多定制需求只是多一个可配置开关。设置项本质上就是teampass_misc表的一行新增一个设置项只需两段代码// 写入管理页面 action 中 DB::insert(prefixTable(misc), [ type my_module, // 分组标识 intitule my_custom_setting, // 设置键名 valeur $postedValue, ]); // 读取任何业务文件中 $SETTINGS (new ConfigManager())-getAllSettings(); $value $SETTINGS[my_custom_setting] ?? default;读取设置的核心类在app/includes/libraries/teampassclasses/configmanager/src/ConfigManager.php这是所有页面、API、后台任务统一取设置的入口。技巧2通过REST API暴露自定义数据如果希望外部系统能读取你的扩展数据直接复用现成的 API 链路是最省力的方式。路由在app/api/index.php控制器在app/api/Controller/Api/新增一个 controller 分支 一个 Action 方法即可JWT 鉴权、速率限制、网络 ACL 全部自动生效无需重复实现安全层// app/api/index.php 路由区新增 } elseif ($controller misc) { require API_ROOT_PATH . /Controller/Api/MiscController.php; $objFeedController new MiscController(); $strMethodName $action . Action; $objFeedController-{$strMethodName}(); }完整的接口契约OpenAPI 3.1 规范在app/api/openapi.json这是你对接前最好的参考书。技巧3让后台任务帮你悄悄干活密码轮换、过期提醒、日志清理这类周期任务TeamPass 有现成的调度框架app/scripts/下的 background tasks 系列。把耗时逻辑写成独立脚本再注册到调度器就能避免阻塞页面请求。避坑指南二次开发最常见的五个坑 ⚠️坑1改了设置不生效原因$SETTINGS是按请求加载的而部分环境开了配置缓存。解决改完设置先清缓存、再刷新页面若仍不生效检查teampass_misc表是否插入了重复行intitule冲突这是新增设置项时最容易踩的雷。坑2自己写了一套加密逻辑原因想当然地认为存个密码用 base64 就行。解决TeamPass 采用多层加密用户盐密钥 服务器密钥数据损坏后几乎不可逆。务必复用cryption()或 CryptManager 类永远不要绕过现有加密机制。项目里有app/scripts/_local/scan_corrupted_items.php等诊断脚本正是因为历史上有过损坏案例。坑3版本升级后扩展代码报错原因TeamPass 每代大版本会调整内部 API如 3.0 升级 phpseclib、3.1 重构用户-角色表。解决升级前看docs/install/upgrade.md和根目录的migrate_3.2.x.php迁移脚本升级后用tests/目录下的 PHPUnit 套件回归你的扩展点。坑4改前端 JS 不生效原因app/pages/*.js.php是后端动态输出的脚本浏览器缓存了旧版本。解决改完js.php记得强制刷新CtrlF5或改app/config/include.php中与版本相关的常量让静态资源 URL 变化从而绕过缓存。坑5API 报 403/429排查没头绪原因403 多半是 CORS 白名单或网络 ACL 限制429 是内置速率限制在起作用。解决在管理后台的 API 设置里检查api_cors_origins与api_rate_limit_per_minute新装环境默认开启 HTTPS 强制非 HTTPS 请求一律 403。从哪里继续给你的行动路线图 官方文档docs/install/installation.md环境搭建、docs/api/api-basic.mdAPI 基础核心源码配置加载app/includes/libraries/teampassclasses/configmanager/、字段管理app/sources/fields.queries.php、API 路由app/api/index.php、后台任务app/scripts/测试参考tests/目录是现成的示例代码库里面每个单测都在演示如何安全地调用项目内部 API比任何文档都直观二次开发的秘诀就一句话找最小的入口做最小的改动用系统的机制解决系统的问题。现在你已经知道了入口在哪里、怎么验证、有哪些坑不妨就从今天开始给 TeamPass 加上你团队真正需要的那个功能吧。愿你的第一次 TeamPass二次开发成为之后一系列定制化模块的起点。✨【免费下载链接】TeamPassCollaborative Passwords Manager项目地址: https://gitcode.com/gh_mirrors/te/TeamPass创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考