beatsad_Vault2Dify/USER_GUIDE.md

Vault2Dify User Guide

English | 中文

Vault2Dify syncs selected Obsidian Markdown notes to Dify Knowledge Bases. It supports local Docker, NAS/Docker, LAN, Tailscale, reverse proxy, and Dify Cloud deployments as long as the Obsidian device can reach the configured Dify service URL.

The plugin UI defaults to English. You can switch between English and Chinese from the language icon in the settings top bar.

1. First-Time Setup

Install the plugin first. See INSTALLATION.md for build and manual installation steps.

Open Settings -> Vault2Dify and complete:

Fill Key -> Test connection -> Add mapping -> Sync

Fill Key

Enter:

• Dify API Key: a Dify Knowledge Base API key that can list knowledge bases and create or update documents.
• Dify service URL: the Dify service root reachable from the device running Obsidian.

Examples:

Deployment	URL
Local Docker on the same computer	http://localhost:5000
NAS/Docker or LAN server	http://dify-host.example.test:5000
NAS through Tailscale	http://tailnet-device.example.test:5000
Reverse proxy or Dify Cloud	https://dify.example.com

The plugin appends Dify API paths such as /v1/datasets automatically. Do not use localhost unless Dify and Obsidian run on the same computer.

Test Connection

Click Test connection to verify the API key, service URL, permissions, and Dify Knowledge Base API response. A successful test loads and saves the current knowledge-base list.

If the test fails, use docs/CONNECTION_TROUBLESHOOTING.md.

Add Mapping

After knowledge bases load:

1. Choose an Obsidian folder, one Markdown note, or the entire vault.
2. Select one or more target Dify Knowledge Bases.
3. Save the mapping.

New installs do not upload notes automatically. Run a manual sync or enable auto sync after mappings are ready.

2. Path Mapping

A mapping controls which Markdown files can sync and where they go.

Obsidian path	Dify Knowledge Bases
Work/ProjectA	Project A, Team Shared
Reading	Personal Reading
Inbox/idea.md	Ideas
Entire vault	Personal Knowledge Base

Rules:

• One Obsidian path can sync to multiple knowledge bases.
• Multiple Obsidian paths can target the same knowledge base.
• Disabled mappings are ignored.
• Deleting a mapping removes local plugin configuration only.
• Deleting a mapping does not delete Obsidian files or Dify remote documents.

Vault2Dify uses the Obsidian file path as the Dify document name, such as Work/ProjectA/meeting-notes.md, so same-name files in different folders remain distinct.

3. Sync Behavior

Manual sync can be started from:

• Ribbon sync icon.
• Command palette: Sync to Dify Knowledge Base.
• Plugin settings: Sync now.

Auto sync can listen for Markdown create, modify, and rename events. The periodic full-check interval acts as a fallback when file events are missed.

Current visible sync presets:

Setting	Choices
Change debounce	8 seconds, 15 seconds, 30 seconds
Full check interval	30 minutes, 60 minutes, Off
Concurrent uploads	2 files, 4 files

Recommended starting point for NAS/Docker or smaller self-hosted Dify deployments:

Auto sync: On
Sync after startup: On
Full check: Every 30 minutes
Change debounce: 8 or 15 seconds
Concurrent uploads: 2 files

Sync rules:

• Only Markdown files matching enabled mappings are eligible.
• Unchanged files are skipped when the stored content hash still matches.
• Existing Dify documents are updated first; new documents are created when no match exists.
• A single failed file does not stop the entire batch.
• Local note deletion is recorded locally and does not automatically delete the remote Dify document.

4. Diagnostics

The status bar stays short, such as Dify: Ready, Dify: Syncing, or Dify: Failed.

The settings page shows:

• Connection state.
• Active URL and last successful URL.
• Recent sync source.
• Total, synced, skipped, and failed task counts.
• Recent sync URL and error.
• Recently failed files.

Enable Debug logs only while diagnosing connection, proxy, API path, or sync failures. Do not share logs that contain API keys or sensitive note content.

5. Privacy and Safety

• The plugin reads Markdown files in the current Obsidian vault.
• Only Markdown files matching enabled path mappings are sent to the configured Dify service URL.
• The Dify API key is stored in local Obsidian plugin data.
• The plugin does not send notes to the plugin author or to any service other than the configured Dify endpoint.
• Local note deletion does not automatically delete Dify remote documents.
• Clearing configuration or sync records affects local plugin data only.

See SECURITY.md for details.

6. FAQ

Should I paste a Dify URL that ends with /v1?

You can. The plugin normalizes known suffixes such as /v1 and /v1/datasets, then appends the Dify API path it needs. The clearest value is still the service root, such as http://dify-host.example.test:5000.

Why does opening /v1/datasets in a browser show 401?

That can mean the URL routes to Dify correctly but needs authentication. The plugin sends Authorization: Bearer <Dify API Key> when loading knowledge bases.

Can one note sync to several knowledge bases?

Yes. A mapping can target multiple Dify Knowledge Bases.

Does deleting a local note delete the Dify document?

No. Local deletion does not automatically delete Dify remote documents. Delete remote documents manually in Dify when needed.

What should I do when a large sync is slow or times out?

Use smaller mappings, lower concurrent uploads to 2 files, and check Dify service load, network latency, and reverse proxy limits.