Dify development

Dify development (router)

Instructions

Use this first when the user wants anything Dify-related. Pick one skill and follow it; do not reinvent HTTP.

Hard rules (every Dify task)

1. Prefer Console API over the browser. Browser only for first /install, OAuth, captcha.
2. Never store passwords or SECRET_KEY in skills, git, or chat logs. Point at a secrets file.
3. Keep DEPLOYMENT_EDITION=COMMUNITY unless there is a real license.
4. If plugin_daemon / api cannot reach the internet, do not "fix" it with iptables FORWARD or a host CONNECT proxy. Host-side .difypkg + local PEP 503 index.
5. Intranet first — follow Dify intranet. Do not pile on cloud-search SaaS unless asked.
6. Judge plugins by GET .../plugin/list and docker logs plugin_daemon (local runtime ready). Clear failed-task UI with POST .../plugin/tasks/delete_all.
7. /agent is Agent Studio. mode: agent-chat is the classic app. Do not mix their URLs.
8. Community RBAC / billing / some RAG publish 403s are feature gates, not CSRF.
9. Service API: same API key + same stable user for upload and run. Console uploads are invalid on /v1.
10. DSL version comes from GET /console/api/app-dsl-version (1.17 = 0.7.0). Never paste a 1.16 0.1.5 export onto 1.17. Every canvas node needs top-level type: "custom" or the UI throws React #130.
11. 1.17 official compose: api/worker/web load .env via env_file. Customized clones often list keys in environment: (then .env alone is ignored) or bind-mount nginx/squid. Trust printenv. After recreating api/web, nginx -s reload. Knobs: Dify compose and config.
12. 1.17 POST /apps/{id}/workflows/draft is graph+features+hash (+ conversation_variables). Top-level environment_variables → 400 extra_forbidden. Env edits: environment_variable_patch.
13. 1.17 Console GET also needs X-CSRF-Token (cookie alone → 401). Unauthenticated / → 307 /signin is normal. Agent Studio is GET /agent, not /apps.
14. Ship text-PDF and OCR as separate apps. Prefer one reusable OCR workflow published as a tool over dropping MinerU on every canvas. An if-else “short text → OCR loop” still puts OCR on that canvas. Product backends (/v1) run published, not draft.
15. On 1.17.0, treat workspace Skill file upload, FastMCP OAuth, QA-segment answer PATCH, and Agent Studio tool calling as unstable until a patch release. Prefer classic workflow + /v1 for anything a customer will demo.
16. Schedule Trigger cannot share a graph with start. File ingest and daily cron are two apps. Cron must be published. There is no one-shot delay queue.
17. Host iron (when host ops docs exist): one LLM on :8001 (Dense 27B TP=4, ctx 262144, --disable-custom-all-reduce; the old “TP=1 / ctx 16384” rule is obsolete). No second LLM. No MTP. Do not compose down -v. Do not pull :latest without a digest. Local wheels only; never pip install torch from PyPI. Do not publish frozen contract-review / kbqa product apps.

新环境：Dify 平台基础配置

This is Dify 1.17 Community platform tune (compose / .env / nginx / workers / timeouts / uploads / SSRF / DB). It is not custom OpenAPI tools, PageIndex, MinerU wrappers, or importing business DSL — those belong in other docs if the operator asks later.

Order:

1. Read runtime on a healthy clone (docker exec … printenv, nginx -T, db command:) — not the .env file alone.
2. Edit the new box. Tables and recreate vs reload: Dify compose and config.
3. Intranet URLs / Squid / NO_PROXY so api can reach :8001 without opening the public net: Dify intranet.
4. Register OpenAI-compatible LLM + embedding + rerank in Console (platform providers only): Dify model providers. curl :8001/v1/models first.
5. Recreate only the services that need it. Verify. Failures: Dify troubleshooting.

Done: console login; Dify can chat via the local LLM; large PDF does not 413; long workflows survive ≥7200s nginx/gunicorn/workflow caps; beat/schedule queues exist if you need cron; SSRF allows host models, not *; still one LLM, no MTP, no unpinned :latest.

Order of work for a new Dify box

1. Compose up, GET /console/api/setup
2. Login (Base64 password + cookie and CSRF on every later GET/POST)
3. Platform tune (section above) — compose/intranet/models
4. Plugins the user named (offline .difypkg; do not install a second OCR stack unless asked)
5. Knowledge base / apps only if they asked — not part of platform tune

If two skills overlap

Operate vs debug → troubleshooting when there is an error, console API when you are only fetching/changing config. Service API vs console → /v1 is for published apps and external callers; /console/api is for you as admin. Catalog vs a domain skill → catalog picks the prefix; the domain skill has the payload. Compose knobs vs a crash → compose-and-config to change a value, troubleshooting when it is already broken. Import vs edit → POST /apps/imports always creates a new app; in-place canvas edits are POST .../workflows/draft plus hash. Shipping a new version is always in-place sync on the SAME app_id — never delete-and-reimport (keys/site/logs/triggers die with the old id; red line in apps-and-workflows). Platform tune vs tools → compose/intranet/model-providers; do not start with agents-and-tools.

Examples

Operator: “new isomorphic box, tune Dify to best” → section 新环境：Dify 平台基础配置, then compose-and-config tables. Do not import business graphs.

Performance Notes

One LLM :8001. Cap Celery at 16. Workflow/nginx/gunicorn ≥ 7200s for long OCR/contract-class runs. json-file 50m×3 in compose.

Troubleshooting

413 / timeout / CSRF / “同步数据中” → Dify troubleshooting. Compose drift (.env vs listed env vs bind-mount) → compose-and-config.