云同步

云同步工作原理

Kanban Pro is a local-first application. Every project is a folder on your filesystem containing Markdown ticket files and a .kanban/ configuration directory. There are no accounts, no proprietary cloud services, and no sign-ups.

To collaborate with others, simply place your project folder inside a cloud-synced directory — iCloud Drive, Dropbox, Google Drive, OneDrive, or any network drive. Every participant opens the same folder in Kanban Pro, and changes propagate automatically through the cloud provider's file sync.

设置共享项目

1. Choose a cloud folder. Open Finder and navigate to your cloud provider's sync directory (e.g. ~/Library/Mobile Documents/com~apple~CloudDocs/ for iCloud Drive, ~/Dropbox/ for Dropbox, or the Google Drive / OneDrive mount in your Finder sidebar).
2. Create a project folder. Create a new folder for your project, e.g. Team Board.
3. Open it in Kanban Pro. Launch Kanban Pro, click Open Folder, and select the folder you just created. Kanban Pro will initialise the .kanban/ directory and you can start adding columns and tickets.
4. Share the folder. Use your cloud provider's sharing features to invite collaborators. On iCloud Drive, right-click the folder and choose Share. On Dropbox or Google Drive, use the sharing dialog. On OneDrive, right-click and select Share → Share with OneDrive. Each collaborator should then open the same synced folder in their own copy of Kanban Pro.

推荐的文件夹布局

When Kanban Pro initialises a project, it creates the following structure inside your chosen folder:

Each ticket is a plain Markdown file with YAML frontmatter for metadata (status, priority, assignee, tags, custom fields). You can read, edit, or back up these files with any tool — including AI coding agents that work directly with the filesystem.

Real-Time Sync & Conflict-Free Editing

Kanban Pro monitors the project folder for filesystem changes using a real-time file watcher. When a collaborator saves a ticket or updates the board configuration, the change is detected within seconds and the UI refreshes automatically.

How conflicts are avoided

• Ticket locking: When you open a ticket for editing, Kanban Pro creates a small lock file inside .kanban/locks/. Other users see the ticket as locked and cannot overwrite your changes. Lock files sync through your cloud provider so all collaborators see the same lock state.
• Atomic writes: Each ticket is a single Markdown file. Kanban Pro writes to a temporary file first, then renames it into place — preventing partial updates even if the cloud provider syncs mid-write.
• Write-finish detection: Kanban Pro waits for files to stabilise (2 seconds for tickets, 1 second for board config) before reading them. This ensures cloud sync has finished writing before the app processes the change.
• Last-write-wins for board config: Column order, settings, and custom field definitions are stored in board.json. If two users change board settings simultaneously, the last write wins — but this is rare in practice since board configuration changes infrequently.

了解锁定文件

The .kanban/locks/ directory contains temporary lock files that indicate which tickets are currently being edited and by whom. Each lock file is a small JSON document:

{
  "ticket": "KAN-42",
  "user": "Alice",
  "device": "Alice-MacBook",
  "timestamp": "2026-03-09T10:30:00Z"
}

Lock files are created when a ticket is opened for editing and removed when the editor is closed. They enable Kanban Pro to show a visual indicator on locked tickets so collaborators know someone is working on them.

Resolving stale locks

If Kanban Pro crashes or a device goes offline, a lock file may remain without being cleaned up. This is called a stale lock.

Kanban Pro also detects locks older than 24 hours and flags them as potentially stale in the UI, giving you the option to force-unlock directly from the app.

云提供商注释

最佳实践

• Keep project folders available offline. Mark your project folder as "Available offline", "Mirror files", "Always Keep on This Device", or "Keep Downloaded" depending on your cloud provider. This avoids delays caused by on-demand file downloads.
• Keep the folder structure shallow. Avoid deeply nested directories — a flat layout improves sync reliability across all providers.
• Check sync status before closing your Mac. Look for sync-in-progress icons in Finder or the menu bar. Shutting down mid-sync can leave partial files that confuse collaborators.
• Maintain free storage. Keep at least 10–15% free disk space on your Mac and at least 20% free cloud storage. Low storage can stall sync or trigger file eviction.
• Use the same cloud provider across the team. Mixing providers (e.g. one person on iCloud, another on Dropbox) requires each person to have their own copy — they will not sync with each other.

故障排除

• Changes not appearing: Check that your cloud provider is actively syncing. Look for sync status icons in Finder or the cloud provider's menu bar icon. Kanban Pro refreshes within seconds of detecting a file change — if the file has not synced yet, the app cannot see it.
• Ticket stuck as locked: See the stale locks section above. You can force-unlock from the app (for locks older than 24 hours) or manually delete the lock file in .kanban/locks/.
• Missing tickets after sync: Some cloud providers delay syncing new files. Wait a moment and check your provider's sync status. If the issue persists, verify the folder is set to sync offline. On iCloud Drive, check that files have not been replaced by .icloud placeholder files.
• Slow initial load: If your cloud provider streams files on demand, the first load may take longer while files are downloaded. Switch to offline or mirror mode for best performance.
• Sync paused unexpectedly: Some cloud providers pause syncing when your Mac is on battery power or has low disk space. Check your provider's menu bar icon for pause indicators and resume syncing if needed.
• Conflicted copy files appearing: If you see files named with "conflicted copy" in Finder, two people likely edited the same file while offline. Open both files to compare, keep the correct version, and delete the conflicted copy.