@nocobase/plugin-ai 2.1.6 → 2.1.8

package/dist/ai/docs/nocobase/ops-management/migration-manager/built-in-tables.md

@@ -0,0 +1,423 @@
+---
+title: "Built-in tables for applications and major plugins"
+description: "Reference for built-in tables of applications and major plugins, covering Migration Manager default strategies, version-control scope, and backup/restore handling."
+keywords: "Migration Manager,version control,backup restore,built-in tables,application configuration,plugin configuration,dataCategory,overwrite,schema-only,skip,NocoBase"
+---
+
+# Built-in tables for applications and major plugins
+
+## Introduction
+
+This list explains common handling for built-in tables of applications and major plugins in Migration Manager, version control, and backup/restore. In most cases, users do not need to adjust tables one by one. Use the default strategy.
+
+These mechanisms focus on different concerns:
+
+- **Migration Manager**: publishes across environments. Common strategies include overwrite, schema-only, and skip.
+- **Version control**: saves and restores key checkpoints during application building.
+- **Backup/restore**: backs up and restores the application runtime state.
+
+The “Data type” column comes from built-in classification. System base data participates in version control; business runtime data does not; runtime temporary data is not backed up.
+
+## Built-in table reference
+
+### Database
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `migrations` | Executed ORM/SQL migration versions | System base data | Schema-only | Included | Backed up |
+
+### Server
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `applicationPlugins` | Plugin list and versions loaded by the application | System base data | Overwrite | Included | Backed up |
+| `applicationVersion` | Application and core version used for upgrade and compatibility checks | System base data | Schema-only | Included | Backed up |
+
+### System settings
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `systemSettings` | Installation-level system parameters and feature switches | System base data | Overwrite | Included | Backed up |
+
+### Client
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `desktopRoutes` | Desktop menu and route structure | System base data | Overwrite | Included | Backed up |
+
+### Multi-space
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `spaces` | Top-level containers for space or workspace isolation | Business runtime data | Schema-only | Not included | Backed up |
+| `spacesUsers` | Membership between users and spaces | Business runtime data | Schema-only | Not included | Backed up |
+
+### App monitoring
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `apps` | Application entries managed by the app monitoring plugin | Business runtime data | Schema-only | Not included | Backed up |
+
+### Main data source
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `collectionCategories` | UI grouping for business collections | System base data | Overwrite | Included | Backed up |
+| `collections` | Business collection fields, indexes, and metadata | System base data | Overwrite | Included | Backed up |
+| `fields` | Field types and constraints under collections | System base data | Overwrite | Included | Backed up |
+
+### Data source manager
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `dataSources` | Main or external database connection configuration | System base data | Overwrite | Included | Backed up |
+| `dataSourcesCollections` | Mapping for synced tables or collections from external sources | System base data | Overwrite | Included | Backed up |
+| `dataSourcesFields` | Mapping between external fields and NocoBase fields | System base data | Overwrite | Included | Backed up |
+| `dataSourcesRoles` | Access roles at data-source level | System base data | Overwrite | Included | Backed up |
+| `dataSourcesRolesResources` | Collections and operations accessible by roles | System base data | Overwrite | Included | Backed up |
+| `dataSourcesRolesResourcesActions` | Allowed actions such as create, read, update, and delete | System base data | Overwrite | Included | Backed up |
+| `dataSourcesRolesResourcesScopes` | Row-level or filter-scope restrictions | System base data | Overwrite | Included | Backed up |
+
+### External database connections
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `databaseServers` | Registered database instances available for connection | System base data | Overwrite | Included | Backed up |
+
+### Visual data modeling
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `graphPositions` | Node positions in graph or flow editors | System base data | Overwrite | Included | Backed up |
+
+### China region field
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `chinaRegions` | Province, city, and district geographic dictionary | Business runtime data | Schema-only | Not included | Backed up |
+
+### Auto-number field
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `sequences` | Sequence table for auto-generated business numbers | System base data | Overwrite | Included | Backed up |
+
+### UI Schema
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `uiButtonSchemasRoles` | Relationship between button permissions and roles | System base data | Overwrite | Included | Backed up |
+| `uiSchemaServerHooks` | Server-side hook extension points for UI configuration | System base data | Overwrite | Included | Backed up |
+| `uiSchemaTemplates` | Reusable form and detail layout fragments | System base data | Overwrite | Included | Backed up |
+| `uiSchemaTreePath` | Materialized paths for component-tree hierarchy | System base data | Overwrite | Included | Backed up |
+| `uiSchemas` | JSON layout definitions for pages and blocks | System base data | Overwrite | Included | Backed up |
+
+### UI templates
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `flowModelTemplateUsages` | Entities instantiated from a flow template | System base data | Overwrite | Included | Backed up |
+| `flowModelTemplates` | Reusable flow-structure templates | System base data | Overwrite | Included | Backed up |
+
+### Flow engine
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `flowModelTreePath` | Materialized paths for flow-model tree structures | System base data | Overwrite | Included | Backed up |
+| `flowModels` | Model definitions for the modern flow engine | System base data | Overwrite | Included | Backed up |
+| `flowSql` | SQL snippets or scripts registered in flows | System base data | Overwrite | Included | Backed up |
+
+### Block templates
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `blockTemplateLinks` | Relationships between pages and block templates | System base data | Overwrite | Included | Backed up |
+| `blockTemplates` | Reusable UI block definitions | System base data | Overwrite | Included | Backed up |
+
+### iframe block
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `iframeHtml` | HTML configuration required by embedded iframes | System base data | Overwrite | Included | Backed up |
+
+### Mobile
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `mobileRoutes` | Mobile app menus and routes | System base data | Overwrite | Included | Backed up |
+
+### Theme editor
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `themeConfig` | Light/dark themes and brand colors | System base data | Overwrite | Included | Backed up |
+
+### Map block
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `mapConfiguration` | Map widget center, zoom, and base-map configuration | System base data | Overwrite | Included | Backed up |
+
+### Public forms
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `publicForms` | External forms and submission-entry configuration | System base data | Overwrite | Included | Backed up |
+
+### Template printing
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `printingTemplates` | Print layouts for list or detail views | System base data | Overwrite | Included | Backed up |
+
+### ACL
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `roles` | Role definitions for permission sets | System base data | Overwrite | Included | Backed up |
+| `rolesResources` | Resources granted to roles | System base data | Overwrite | Included | Backed up |
+| `rolesResourcesActions` | Actions allowed on resources, such as view and update | System base data | Overwrite | Included | Backed up |
+| `rolesResourcesScopes` | Data filter scopes visible to roles | System base data | Overwrite | Included | Backed up |
+| `rolesUsers` | Many-to-many relationship between users and roles | Business runtime data | Schema-only | Not included | Backed up |
+
+### Authentication
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `authenticators` | Password and third-party login method configuration | System base data | Overwrite | Included | Backed up |
+| `tokenControlConfig` | Session duration and refresh strategy | System base data | Overwrite | Included | Backed up |
+| `issuedTokens` | Issued login or API access tokens | Business runtime data | Schema-only | Not included | Backed up |
+| `tokenBlacklist` | Tokens that have been logged out or forcibly invalidated | Business runtime data | Schema-only | Not included | Backed up |
+| `usersAuthenticators` | Bindings between users and authentication methods | Business runtime data | Schema-only | Not included | Backed up |
+
+### Two-factor authentication
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `twoFactorAuthSettings` | 2FA methods and user-level switches | System base data | Overwrite | Included | Backed up |
+
+### API keys
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `apiKeys` | Open API keys and permission scopes | Business runtime data | Schema-only | Not included | Backed up |
+
+### Password policy
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `passwordPolicy` | Password complexity and expiration policies | System base data | Overwrite | Included | Backed up |
+| `lockedUsers` | Accounts temporarily locked by policy | Business runtime data | Schema-only | Not included | Backed up |
+| `userPasswordHistory` | Recent password hashes used to prevent reuse | Business runtime data | Schema-only | Not included | Backed up |
+
+### IP restriction
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `ipRestrictionConfig` | IP allowlist or blocklist rules | System base data | Overwrite | Included | Backed up |
+
+### Users
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `users` | Login accounts, profiles, and basic status | Business runtime data | Schema-only | Not included | Backed up |
+
+### Departments
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `departments` | Department tree in the organization structure | Business runtime data | Overwrite | Not included | Backed up |
+| `departmentsRoles` | Bindings between departments and default roles | Business runtime data | Overwrite | Not included | Backed up |
+| `departmentsUsers` | Relationships between users and departments | Business runtime data | Schema-only | Not included | Backed up |
+
+### User data sync
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `userDataSyncSources` | External identity source or account-system connection configuration | System base data | Overwrite | Included | Backed up |
+| `userDataSyncRecords` | Execution records for synchronization jobs | Business runtime data | Schema-only | Not included | Backed up |
+| `userDataSyncRecordsResources` | Tables or resources involved in synchronization jobs | Business runtime data | Schema-only | Not included | Backed up |
+| `userDataSyncTasks` | Synchronization task records | Business runtime data | Schema-only | Not included | Backed up |
+
+### Workflow
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `flow_nodes` | Workflow nodes | System base data | Overwrite | Included | Backed up |
+| `workflows` | Automation flow charts, triggers, and node configuration | System base data | Overwrite | Included | Backed up |
+| `jobs` | Execution result of each node in a workflow run | Business runtime data | Schema-only | Not included | Backed up |
+| `executions` | Status, inputs, outputs, and log indexes for workflow runs | Business runtime data | Schema-only | Not included | Backed up |
+| `userWorkflowTasks` | Task-count statistics for users | Business runtime data | Schema-only | Not included | Backed up |
+| `workflowCategories` | Workflow grouping in the UI | Business runtime data | Overwrite | Not included | Backed up |
+| `workflowCategoryRelations` | Many-to-many relationship between workflows and categories | Business runtime data | Overwrite | Not included | Backed up |
+| `workflowStats` | Aggregated metrics such as run count and success rate | Business runtime data | Schema-only | Not included | Backed up |
+| `workflowTasks` | Task execution records for automation nodes | Business runtime data | Schema-only | Not included | Backed up |
+| `workflowVersionStats` | Execution and performance statistics by workflow version | Business runtime data | Schema-only | Not included | Backed up |
+
+### Workflow approval
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `approvalAudienceUsers` | Relationship between approval audiences and users | Business runtime data | Schema-only | Not included | Backed up |
+| `approvalAudiences` | Approval notification or participation scope grouped by role or user | Business runtime data | Schema-only | Not included | Backed up |
+| `approvalExecutions` | Runtime status and current node of an approval flow | Business runtime data | Schema-only | Not included | Backed up |
+| `approvalMsgTpls` | Message templates for approval notices and tasks | Business runtime data | Overwrite | Not included | Backed up |
+| `approvalRecords` | Approval tasks and processing results from a personal view | Business runtime data | Schema-only | Not included | Backed up |
+| `approvals` | Approval-flow templates and step configuration | Business runtime data | Schema-only | Not included | Backed up |
+
+### Workflow manual node
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `workflowManualTasks` | Manual-node tasks that require human handling | Business runtime data | Schema-only | Not included | Backed up |
+
+### Workflow CC
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `workflowCcTasks` | Read-only copied workflow tasks | Business runtime data | Schema-only | Not included | Backed up |
+
+### Notification manager
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `notificationChannels` | Delivery channel configuration such as in-app messages and email | System base data | Overwrite | Included | Backed up |
+| `notificationSendLogs` | Delivery status and failure reason for notifications | Business runtime data | Schema-only | Not included | Backed up |
+
+### In-app messages
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `notificationInAppMessages` | In-app messages received by users | Business runtime data | Schema-only | Not included | Backed up |
+
+### Verification
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `verifiers` | Configuration for who can initiate or complete verification | System base data | Overwrite | Included | Backed up |
+| `otpRecords` | SMS or email OTP issue and verification records | Business runtime data | Schema-only | Not included | Backed up |
+| `usersVerifiers` | Bindings between users and verification channels or entities | Business runtime data | Schema-only | Not included | Backed up |
+
+### Mail manager
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `mailGeneralSettings` | Global mail behavior and default values | System base data | Overwrite | Included | Backed up |
+| `mailSettings` | Mail plugin switches and parameters | System base data | Overwrite | Included | Backed up |
+| `mailAccounts` | Sending mailbox accounts and SMTP configuration | Business runtime data | Overwrite | Not included | Backed up |
+| `mailMassMessages` | Mass-mail tasks and recipient batches | Business runtime data | Schema-only | Not included | Backed up |
+| `mailMessageLabels` | Mail category label definitions | Business runtime data | Schema-only | Not included | Backed up |
+| `mailMessageNotes` | Internal notes for individual emails | Business runtime data | Schema-only | Not included | Backed up |
+| `mailMessages` | Indexes for synced or sent email content | Business runtime data | Schema-only | Not included | Backed up |
+| `mailTemplates` | HTML/text templates for notification emails | Business runtime data | Schema-only | Not included | Backed up |
+| `mailmessagelabelsMailmessages` | Join table between emails and many-to-many labels | Business runtime data | Schema-only | Not included | Backed up |
+| `mailmessagelabelsMailmessagesRel` | Auxiliary fields or extension table for mail-label relationships | Business runtime data | Schema-only | Not included | Backed up |
+
+### AI
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `aiEmployees` | AI employee profiles: nickname, skills, models, knowledge bases, and related configuration | System base data | Overwrite | Included | Backed up |
+| `aiSettings` | AI basic settings | System base data | Overwrite | Included | Backed up |
+| `rolesAiEmployees` | Relationship between AI employees and roles | System base data | Overwrite | Included | Backed up |
+| `llmServices` | LLM providers and model endpoint configuration | System base data | Overwrite | Included | Backed up |
+| `aiContextDatasources` | Business collections, fields, and filters queryable by AI employees | Business runtime data | Schema-only | Not included | Backed up |
+| `aiConversations` | Conversation context for sessions, topics, and message threads | Business runtime data | Schema-only | Not included | Backed up |
+| `aiFiles` | Uploaded files and storage references generated by the AI plugin | Business runtime data | Schema-only | Not included | Backed up |
+| `aiMessages` | User and assistant messages in conversations | Business runtime data | Schema-only | Not included | Backed up |
+| `aiToolMessages` | Requests and responses for function or tool calls | Business runtime data | Schema-only | Not included | Backed up |
+| `usersAiEmployees` | Relationship between user custom prompts and AI employees | Business runtime data | Schema-only | Not included | Backed up |
+| `lcCheckpointBlobs` | Binary blocks for LLM conversation checkpoints | Runtime temporary data | Schema-only | Not included | Not backed up |
+| `lcCheckpointWrites` | Incremental checkpoint write records | Runtime temporary data | Schema-only | Not included | Not backed up |
+| `lcCheckpoints` | LangGraph checkpoint metadata for recoverable conversations | Runtime temporary data | Schema-only | Not included | Not backed up |
+
+### AI knowledge base
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `aiKnowledgeBaseDocs` | Document chunks and index metadata stored in knowledge bases | Business runtime data | Schema-only | Not included | Backed up |
+| `aiKnowledgeBase` | Knowledge-base type, external ID, and base information | Business runtime data | Schema-only | Not included | Backed up |
+| `aiVectorDatabases` | Vector database service and connection configuration | Business runtime data | Schema-only | Not included | Backed up |
+| `aiVectorStoreConfig` | Relationship between vector database connections and embedding models | Business runtime data | Schema-only | Not included | Backed up |
+
+### Environment variables
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `environmentVariables` | Deployment-related key-value entries, such as secret placeholder names | System base data | Schema-only | Included | Backed up |
+
+### Migration manager
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `migrationRules` | Rules and scope configuration in the migration manager | System base data | Schema-only | Included | Backed up |
+
+### Backup manager
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `backupSettings` | Automatic backup and retention policy | Business runtime data | Overwrite | Not included | Backed up |
+
+### Audit logs
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `auditTrails` | Trace of who operated on which resources and when | Business runtime data | Schema-only | Not included | Backed up |
+
+### Async tasks
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `asyncTasks` | Queue, status, and result of long-running tasks | Business runtime data | Schema-only | Not included | Backed up |
+
+### Record history
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `recordHistoryCollections` | Collections with field history enabled | System base data | Overwrite | Included | Backed up |
+| `recordHistoryFields` | Fields that need history records | System base data | Overwrite | Included | Backed up |
+| `recordHistoryTemplate` | Display template for history records | System base data | Overwrite | Included | Backed up |
+| `recordFieldHistories` | Historical values and timeline for field changes | Business runtime data | Schema-only | Not included | Backed up |
+| `recordFieldSnapshots` | Snapshot proof of field values at a point in time | Business runtime data | Schema-only | Not included | Backed up |
+| `recordHistories` | Versioned change records for entire records | Business runtime data | Schema-only | Not included | Backed up |
+
+### File manager
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `storages` | Local, S3, OSS, and other storage bucket configuration | System base data | Overwrite | Included | Backed up |
+| `attachments` | File attachment metadata associated with business records | Business runtime data | Schema-only | Not included | Backed up |
+
+### Localization
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `localizationTexts` | Keys and default text awaiting translation | System base data | Overwrite | Included | Backed up |
+| `localizationTranslations` | Actual translated content for each language | System base data | Overwrite | Included | Backed up |
+
+### Localization tester
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `localeTester` | Entries used for localization debugging or testing | Business runtime data | Schema-only | Not included | Backed up |
+
+### Custom request
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `customRequests` | Custom HTTP request actions with URL and method configuration | System base data | Overwrite | Included | Backed up |
+| `customRequestsRoles` | Roles allowed to call custom requests | System base data | Overwrite | Included | Backed up |
+
+### Custom variables
+
+| Table | Description | Data type | Default migration strategy | Version control | Backup/restore |
+| --- | --- | --- | --- | --- | --- |
+| `customVariables` | Variable definitions and default values available to flows or globally | System base data | Overwrite | Included | Backed up |
+
+## User-defined tables
+
+User-defined tables are treated as business data by default. In most cases, migrate only the table structure and choose schema-only.
+
+If a user-defined table stores business configuration, categories, templates, rules, or other metadata, and those records should be synchronized from development to staging or production with the release, choose overwrite based on the business scenario.
+
+If a user-defined table stores runtime data such as customers, orders, tickets, approval records, messages, or logs, avoid overwriting production records.

package/dist/ai/docs/nocobase/ops-management/migration-manager/index.md

@@ -1,5 +1,8 @@
 ---
 pkg: '@nocobase/plugin-migration-manager'
+title: "Migration Manager"
+description: "Operations migration: migrate application configuration from one environment to another, with schema-only, overwrite, and skip rules. Depends on Backup Manager."
+keywords: "Migration Manager,Migration,application configuration migration,migration rules,schema-only,overwrite,skip,database migration,operations,NocoBase"
 ---
 
 # Migration Manager
@@ -26,17 +29,15 @@ The Migration Manager transfers tables and data from the primary database based
 
 ### Built-in Rules
 
-Migration Manager supports five built-in rules:
+Migration Manager supports the following three rules:
 
-- **Schema-only:** Only migrates the structure—no data is moved.
-- **Overwrite:** Deletes target table records, then inserts new data.
-- **Upsert:** Updates existing records (by primary key) or inserts new ones.
-- **Insert-ignore:** Inserts new records; skips existing ones.
-- **Skip:** No changes to the table.
+- **Schema-only:** Only synchronizes table structures. No data is inserted or updated.
+- **Overwrite:** Clears existing table records, then inserts new data.
+- **Skip:** Does nothing to the table.
 
-**Additional notes:**
-- "Overwrite," "Upsert," and "Insert-ignore" all synchronize table structure changes.
-- Tables with auto-increment IDs or no primary keys do not support "Upsert" or "Insert-ignore."
+**Notes:**
+- Overwrite also synchronizes table-structure changes.
+- User-defined business data tables usually use schema-only to avoid overwriting production business data.
 
 ### Detailed Design
 
@@ -46,6 +47,8 @@ Migration Manager supports five built-in rules:
 
 Configure migration rules
 
+For the tables behind default strategies, see: [Built-in tables for applications and major plugins](./built-in-tables.md).
+
 ![20250102205450](https://static-docs.nocobase.com/20250102205450.png)
 
 Enable independent rules

package/dist/ai/docs/nocobase/ops-management/release-management/index.md

@@ -1,52 +1,139 @@
+---
+title: "Release Management"
+description: "Operations release best practices: use version control to record development checkpoints, multi-app architecture to split business modules, Backup Manager for disaster recovery, and Migration Manager to publish across development, staging, and production environments."
+keywords: "Release Management,Release,multi-environment deployment,version control,multi-app,Backup Manager,Migration Manager,development staging production,NocoBase"
+---
+
 # Release Management
 
 ## Introduction
 
-In real-world applications, to ensure data security and application stability, multiple environments are typically deployed, such as a development environment, a pre-release environment, and a production environment. This document provides examples of two common no-code development processes and explains in detail how to implement release management in NocoBase.
+Release management standardizes how an application moves from development to production. It is not a single operation. It is a repeatable, verifiable, and recoverable release process.
+
+Keep production stable. Complete configuration changes in development first, validate them in staging, then publish them to production. Migration files, backups, execution logs, and validation results generated during release should be retained for troubleshooting and rollback.
+
+Recommended environments:
+
+```text
+Development environment -> Staging environment -> Production environment
+```
+
+Development is used for configuration and adjustment. Staging restores production constraints and validates the release result. Production carries real business traffic. Clear responsibilities make the release process easier to manage.
+
+## Release Model
+
+NocoBase release management usually combines five capabilities.
+
+| Capability | Problem solved | Stage |
+| --- | --- | --- |
+| Version control | Saves key checkpoints during development and provides rollback points for configuration changes | Development |
+| Variables and secrets | Isolates environment-specific configuration and sensitive information | Development, staging, and production release |
+| Multi-app | Splits system boundaries by business module and reduces release impact between modules | Architecture planning and team collaboration |
+| Backup Manager | Saves a recoverable production state for release failures and daily incidents | Before release and daily disaster recovery |
+| Migration Manager | Publishes configuration and structure changes to the target environment | Staging and production release |
+
+## Environment Configuration: Use Variables and Secrets
+
+Variables and secrets isolate environment-specific configuration and sensitive information. Development, staging, and production should use their own variables and secrets.
+
+Identify environment-related configuration during development. Database connections, third-party service addresses, test accounts, access tokens, API keys, and webhook URLs should not be hardcoded in pages, workflows, or plugin settings. Reference them through variables and secrets whenever possible. When migrating to staging or production, you only need to complete missing target-environment values as prompted, and production secrets will not be written into migration content.
+
+Related documentation: [Variables and Secrets](../variables-and-secrets/index.md).
+
+## Development Stage: Record Recoverable Checkpoints
+
+Development changes frequently. Use version control to save key checkpoints. Before a major configuration change, create a version. After adjusting data models, pages, permissions, workflows, or plugin settings, create another version.
+
+Write version descriptions with clear business meaning. For example, “adjust customer follow-up page and field permissions,” “add ticket escalation workflow,” or “optimize asset request approval flow.” Clear descriptions make later validation, comparison, and recovery easier.
+
+Version control mainly serves the development process. It is suitable for undoing a configuration change or preserving a milestone. After entering the release stage, synchronize configuration changes through Migration Manager. Use Backup Manager when production needs recovery.
+
+Related documentation: [Version control](../version-control/index.md).
+
+## Module Splitting: Control Release Boundaries
+
+For small systems, start with a single app. A single app is simple to deploy and works well for prototypes, small internal systems, and early-stage projects.
 
-## Installation
+As business complexity grows, one app may contain more pages, tables, permissions, and workflows. One configuration change may affect several teams. One release may involve several modules. At that point, consider splitting business boundaries with multi-app architecture.
 
-Three plugins are essential for release management. Please ensure all of the following plugins are activated.
+Multi-app works well when split by business responsibility, such as CRM, tickets, assets, HR, reports, and operations backend. Each app can be developed, tested, released, and rolled back independently. High-change modules, high-risk modules, and modules serving different user groups are often better separated.
 
-### Environment Variables
+Plan shared capabilities before splitting. Users, organizations, authentication, permissions, and cross-app shared data all affect later release methods. Clearer boundaries make release impact easier to control.
 
-- Built-in plugin, installed and activated by default.
-- Provides centralized configuration and management of environment variables and keys, used for sensitive data storage, reusable configuration data, environment-based isolation, etc. ([View Documentation](../variables-and-secrets/index.md)).
+A split release chain usually looks like this:
 
-### Backup Manager
+```text
+CRM app: Development environment -> Staging environment -> Production environment
+Ticket app: Development environment -> Staging environment -> Production environment
+Asset app: Development environment -> Staging environment -> Production environment
+```
 
-- Available only in the Professional edition or higher ([Learn more](https://www.nocobase.com/en/commercial)).
-- Supports backup and restoration, including scheduled backups, ensuring data security and quick recovery. ([View Documentation](../backup-manager/index.mdx)).
+Related documentation: [Multi-app management](../../multi-app/multi-app/index.md).
 
-### Migration Manager
+## Pre-release Preparation: Confirm Recovery Capability
 
-- Available only in the Professional edition or higher ([Learn more](https://www.nocobase.com/en/commercial)).
-- Used to migrate application configurations from one application environment to another ([View Documentation](../migration-manager/index.md)).
+Backup is the safety baseline for production release. Create a pre-release backup before publishing to production. For important releases, verify that the backup can be restored in an independent environment.
 
-## Common No-Code Development Processes
+Pre-release backups and scheduled daily backups serve different purposes. Scheduled backups handle misoperation, data corruption, and infrastructure failures. Pre-release backups support quick recovery after release failure. Both should be part of the production operations strategy.
 
-### Single Development Environment, One-Way Release
+Before release, confirm that the backup task has completed and that the backup file can be downloaded or accessed. For important releases, perform a restore verification in an independent environment.
 
-This approach suits simple development processes. There is one development environment, one pre-release environment, and one production environment. Changes flow from the development environment to the pre-release environment and are finally deployed to the production environment. In this process, only the development environment can modify configurations—neither the pre-release nor the production environment allows modifications.
+Backups should cover the database, user-uploaded files, and storage content required by the application runtime. Database-only records are not enough for full recovery.
+
+Related documentation: [Backup Manager](../backup-manager/index.mdx).
+
+## Release Execution: Migrate to the Target Environment
+
+Migration Manager publishes application configuration from one environment to another. Common migration content includes application configuration, table structures, plugin configuration, and some data that needs to be migrated.
+
+Publish to staging first. After the migration file passes staging validation, use the same file for production release.
 
 ![20250106234710](https://static-docs.nocobase.com/20250106234710.png)
 
-When configuring migration rules, select **“Overwrite”** for built-in tables in the core and plugins if needed; for all others, you can keep the default settings if there are no special requirements.
+### Publish to Staging
 
-![20250105194845](https://static-docs.nocobase.com/20250105194845.png)
+After generating a migration file from development, execute it in staging first. Staging should be as close to production as possible, including core version, plugin versions, variables, secrets, permission configuration, and external-system connection methods. After execution, validate core pages, permission rules, workflows, and external integrations.
+
+After staging validation passes, keep the same migration file for production release. Do not modify the migration file right before production. If changes are needed, go back to development, regenerate the file, and validate it again in staging.
+
+### Publish to Production
+
+Schedule a maintenance window for production release. Notify users before the release, stop user access or switch to a maintenance page, and avoid new business data writes during migration. In cluster or multi-node deployments, scale the application down to one node before migration.
+
+After confirming that the pre-release backup has completed, execute the migration file that passed staging validation. After migration, validate core business flows first, then restore user access. In multi-node deployments, restore the node count after validation passes.
 
-### Multiple Development Environments, Merged Release
+Migration files, backups, and execution logs are stored in their respective features. Internal release records can add release time, executor, validation result, and backup information for later troubleshooting and rollback.
 
-This approach suits multi-person collaboration or complex projects. Several parallel development environments can be used independently, and all changes are merged into a single pre-release environment for testing and verification before being deployed to production. In this process, only the development environment can modify configurations—neither the pre-release nor the production environment allows modifications.
+### Migration Rules
 
-![20250107103829](https://static-docs.nocobase.com/20250107103829.png)
+Migration rules decide how tables and records are handled in the target environment. Common strategies include overwrite, schema-only, and skip. Before configuring rules, first distinguish application and plugin built-in tables from user-defined tables.
 
-When configuring migration rules, select **“Insert or Update”** for built-in tables in the core and plugins if needed; for all others, you can keep the default settings if there are no special requirements.
+Application and plugin built-in tables usually follow the default strategy and use overwrite first. Examples include pages, menus, blocks, permissions, and workflows. During release, development configuration is usually treated as the source of truth and synchronized to staging and production.
 
-![20250105194942](https://static-docs.nocobase.com/20250105194942.png)
+User-defined tables should be judged by business purpose. Tables that carry real business data usually migrate structure only and use schema-only, avoiding overwrites of production data. Some user-defined tables that store metadata such as configuration, categories, templates, or rules can use overwrite depending on the business scenario.
 
-## Rollback
+For the tables behind default strategies, see [Built-in tables for applications and major plugins](../migration-manager/built-in-tables.md).
 
-Before executing a migration, the system automatically creates a backup of the current application. If the migration fails or the results are not as expected, you can roll back and restore via the [Backup Manager](../backup-manager/index.mdx).
+![20250105194845](https://static-docs.nocobase.com/20250105194845.png)
+
+Migration Manager mainly handles application configuration and data in the main database. External data sources, sub-app data, and some storage-directory content should be handled separately according to the actual situation.
+
+Related documentation: [Migration Manager](../migration-manager/index.md).
+
+## Rollback and Recovery
+
+When a release fails, first use the pre-release backup through the Backup Manager plugin. Before restoring, confirm that the backup file is available and follow the UI prompts to complete restoration.
+
+If the current production environment can still access Backup Manager and only the migration execution failed, restore the pre-release backup directly in the current environment. After recovery, record the failure cause and handling result to avoid repeating the same issue in later releases.
+
+If the current environment is unstable, or you want to reduce the risk of repeated repair attempts in a faulty environment, prepare an independent environment and restore the pre-release backup there. After restoration, validate core business flows first, then switch traffic to the recovered environment.
 
 ![20250105195029](https://static-docs.nocobase.com/20250105195029.png)
+
+## Related Documentation
+
+- [Variables and Secrets](../variables-and-secrets/index.md)
+- [Version control](../version-control/index.md)
+- [Multi-app management](../../multi-app/multi-app/index.md)
+- [Backup Manager](../backup-manager/index.mdx)
+- [Migration Manager](../migration-manager/index.md)