Instatic导入API文档端点说明与示例请求【免费下载链接】InstaticInstatic is a modern self-hosted visual CMS - get it running in 1 minute项目地址: https://gitcode.com/GitHub_Trending/in/InstaticInstatic是一个现代化的自托管可视化CMS系统提供了完整的导入API让开发者能够通过编程方式导入网站内容和数据。本文将详细介绍Instatic的导入API端点、请求格式和使用示例帮助您快速掌握数据导入的完整流程。导入API概述Instatic的导入API位于/admin/api/cms/import/路径下支持两种主要导入方式静态站点导入和CMS捆绑包导入。这些API端点允许您将HTML页面、CSS样式表、媒体文件以及完整的CMS数据结构导入到Instatic实例中。核心导入端点1. CMS捆绑包预览端点端点POST /admin/api/cms/import/preview功能预览CMS捆绑包内容显示导入前后的差异对比帮助用户确认导入操作的影响。请求示例POST /admin/api/cms/import/preview Content-Type: application/json { site: { name: 示例网站, settings: { ... } }, tables: [...], rows: [...], media: [...], mediaFolders: [...], redirects: [...] }响应示例{ meta: { exportedAt: 2024-01-15T10:30:00Z, sourceSiteName: 示例网站, schemaVersion: 1.0.0 }, tables: [ { id: pages, name: 页面, kind: system, inBundle: 12, willReplace: 3, willAdd: 9, currentLocal: 15 } ], rowConflicts: [ { tableId: posts, tableName: 文章, rowId: post-123, rowTitle: 我的文章, slug: my-post, existingRowId: post-456, suggestedSlug: my-post-2 } ], totals: { rows: 45, mediaFiles: 23, mediaEmbedded: true, mediaFolders: 5, redirects: 8 } }2. CMS捆绑包导入端点端点POST /admin/api/cms/import?strategystrategy功能执行实际的CMS数据导入支持三种导入策略replace默认删除所有现有数据从捆绑包重新导入merge-add仅添加本地不存在的新行跳过已存在的行merge-overwrite添加新行并更新已存在的行请求示例POST /admin/api/cms/import?strategymerge-add Content-Type: application/json { site: { ... }, tables: [...], rows: [...], media: [...], mediaFolders: [...], redirects: [...] }响应示例{ imported: { tables: 3, rows: 45, mediaFiles: 23, mediaFolders: 5, redirects: 8 }, warnings: [ { kind: duplicate-slug, message: 页面slug about 已存在已重命名为 about-2 } ] }3. 归档文件导入端点端点POST /admin/api/cms/import/archive?strategystrategy功能直接从ZIP归档文件导入这是用户界面使用的标准导入方式。归档文件包含.instatic/site-bundle.json清单文件和所有媒体资源。请求示例POST /admin/api/cms/import/archive?strategyreplace Content-Type: multipart/form-data file: ZIP文件权限和安全性Instatic的导入API具有精细的权限控制所有导入策略都需要data.import权限replace策略额外需要content.manage权限和step-up验证双重确认包含site结构的捆绑包需要site.structure.edit权限这种权限矩阵确保了敏感操作的安全防止具有结构编辑权限但没有内容管理权限的用户意外删除所有数据行。静态站点导入流程静态站点导入通过src/core/siteImport/模块处理支持以下文件类型HTML页面自动解析为页面结构CSS样式表转换为可编辑的样式规则或保留为文件媒体文件图片、视频、字体等资源JavaScript脚本保留为运行时脚本或转换为依赖项冲突解决机制导入过程中可能遇到的冲突类型1. 页面slug冲突当导入的页面slug与现有页面冲突时系统提供以下选项自动重命名添加数字后缀如about-2跳过不导入冲突页面覆盖替换现有页面自定义重命名手动指定新slug2. 类名冲突CSS类名冲突处理特别智能共享定义所有样式表中定义相同的类 → 合并不同定义样式表定义不同 → 标记为冲突默认自动重命名Bootstrap类如row、col-xl-3等框架类不标记为冲突3. 设计令牌冲突颜色和字体令牌冲突处理令牌重命名自动重命名导入的令牌变量引用更新自动更新所有var(--old)引用为var(--new)跳过/覆盖用户可选择跳过或覆盖现有令牌导入策略详解替换策略replace完全替换现有数据适用于全新安装或完整迁移删除所有现有数据表、行、媒体和重定向从捆绑包重新导入所有内容需要最高权限级别和step-up验证合并-添加策略merge-add安全地添加新内容仅添加ID不存在的新行跳过已存在的行保持原样适用于内容补充合并-覆盖策略merge-overwrite更新和添加内容添加新行更新已存在行的内容保持其他行不变适用于内容同步错误处理和验证验证机制类型验证使用TypeBox模式验证所有输入数据完整性检查验证数据关系的完整性权限验证检查用户是否具有执行操作的权限错误响应导入API返回标准化的错误响应{ error: 错误描述, details: 可选详细信息 }警告信息导入过程中可能产生的警告dropped-at-rule不支持的CSS规则被忽略asset-upload-failed媒体文件上传失败duplicate-class重复的CSS类定义external-font外部字体被跳过最佳实践和示例示例1完整网站迁移# 1. 从源系统导出为SiteBundle格式 # 2. 预览导入影响 curl -X POST \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d site-bundle.json \ https://your-instance.com/admin/api/cms/import/preview # 3. 执行替换导入 curl -X POST \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d site-bundle.json \ https://your-instance.com/admin/api/cms/import?strategyreplace示例2增量内容更新# 仅添加新内容不覆盖现有内容 curl -X POST \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d new-content.json \ https://your-instance.com/admin/api/cms/import?strategymerge-add示例3通过归档文件导入# 使用ZIP归档文件导入 curl -X POST \ -H Authorization: Bearer token \ -F filesite-export.zip \ https://your-instance.com/admin/api/cms/import/archive?strategymerge-overwrite高级功能原子性保证所有数据库变更都在单个事务中执行确保导入操作的原子性成功所有变更一起提交失败所有变更一起回滚媒体文件在事务成功后单独处理性能优化批量处理大量数据分批处理内存管理流式处理大文件进度跟踪实时导入进度反馈扩展性插件支持可通过插件扩展导入功能自定义处理器支持自定义数据转换Webhook集成导入完成后触发事件故障排除常见问题权限不足检查用户是否具有data.import权限对于replace策略还需要content.manage权限数据格式错误验证JSON格式是否符合SiteBundle模式检查必需字段是否完整内存不足分批导入大量数据使用归档文件导入减少内存使用冲突解决使用预览端点识别冲突选择合适的解决策略调试建议启用详细日志记录使用预览端点测试导入从小批量数据开始测试检查服务器错误日志总结Instatic的导入API提供了强大而灵活的数据导入功能支持从简单的内容更新到完整的网站迁移。通过精细的权限控制、智能的冲突解决机制和多种导入策略您可以安全、高效地将数据导入到Instatic实例中。无论是通过编程方式集成到自动化工作流还是通过用户界面进行手动导入Instatic都提供了完整的解决方案。记住始终先使用预览端点测试导入选择合适的导入策略并确保具有必要的权限。通过合理利用这些API端点您可以轻松实现 网站内容的批量迁移 多环境数据同步 定期内容备份和恢复 自动化部署流程开始使用Instatic导入API让您的网站内容管理更加高效和可靠【免费下载链接】InstaticInstatic is a modern self-hosted visual CMS - get it running in 1 minute项目地址: https://gitcode.com/GitHub_Trending/in/Instatic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考