docs(self-host): document Community 1.17 env, CSRF, and plugin runtime failures - #1019
Open
kabishou11 wants to merge 2 commits into
Open
docs(self-host): document Community 1.17 env, CSRF, and plugin runtime failures#1019kabishou11 wants to merge 2 commits into
kabishou11 wants to merge 2 commits into
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The zh/ja pages introduce broken cross-page anchor links (to translated headings) and should be fixed before merging to avoid shipping dead links.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the self-host troubleshooting docs for Community Edition 1.17 to cover new operator failure modes (login/CSRF/session behavior, env-file injection quirks, timeouts, WebSocket 502s, plugin runtime/413 issues) and corrects outdated nginx 502 guidance that suggested hardcoding container IPs.
Changes:
- Replaces the stale “502 Bad Gateway” workaround with guidance aligned to Compose DNS + nginx template behavior, including reload vs recreate.
- Adds new troubleshooting sections for environment file injection, WebSocket collaboration, and plugin install/runtime readiness (incl. 413 sizing constraints).
- Expands “Common Issues” to document login encryption expectations, CSRF requirements, session expiry behavior, SECRET_KEY implications, and timeout/upload nuances.
File summaries
| File | Description |
|---|---|
| en/self-host/deploy/troubleshooting/docker-issues.mdx | Updates Compose/nginx 502 troubleshooting; adds env-file, WebSocket, and plugin runtime sections. |
| en/self-host/deploy/troubleshooting/common-issues.mdx | Adds login/CSRF/session/SECRET_KEY guidance and clarifies timeouts/uploads. |
| zh/self-host/deploy/troubleshooting/docker-issues.mdx | Chinese translation of the updated Docker troubleshooting content. |
| zh/self-host/deploy/troubleshooting/common-issues.mdx | Chinese translation of the updated common issues content (includes new anchors/links). |
| ja/self-host/deploy/troubleshooting/docker-issues.mdx | Japanese translation of the updated Docker troubleshooting content. |
| ja/self-host/deploy/troubleshooting/common-issues.mdx | Japanese translation of the updated common issues content (includes new anchors/links). |
Review details
Suppressed comments (2)
zh/self-host/deploy/troubleshooting/common-issues.mdx:104
- 这里链接到
/zh/.../environments#web-frontend-service，但目标页面对应章节标题是“Web 前端服务”（没有{#web-frontend-service}稳定 ID），因此该锚点不会匹配。建议改为链接到该中文章节的实际 slug。
### 节点执行超时
在 `.env` 中设置 `TEXT_GENERATION_TIMEOUT_MS`，控制前端流式输出的停滞超时。详见 [TEXT_GENERATION_TIMEOUT_MS](/zh/self-host/deploy/configuration/environments#web-frontend-service)。
ja/self-host/deploy/troubleshooting/common-issues.mdx:104
/ja/.../environments側の該当セクション見出しは「Web フロントエンドサービス」で、{#web-frontend-service}のような固定 ID は付いていません。そのため#web-frontend-serviceは解決されず、見出し slug に合わせたフラグメントにする必要があります。
### ノード実行タイムアウト
ノードごとのフロントエンドストリーミング停滞タイムアウトを制御するには、`.env` で `TEXT_GENERATION_TIMEOUT_MS` を設定してください。詳細は [TEXT_GENERATION_TIMEOUT_MS](/ja/self-host/deploy/configuration/environments#web-frontend-service) を参照してください。
- Files reviewed: 6/6 changed files
- Comments generated: 5
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
141
to
145
| If you see: | ||
| ``` | ||
|
|
||
| ```text | ||
| FATAL: no pg_hba.conf entry for host "172.19.0.7", user "postgres", database "dify", no encryption | ||
| ``` |
|
|
||
| 両方を上げてください。API 側だけを上げると、nginx が API より先に **413** を返します。画像、動画、音声にはそれぞれ `UPLOAD_*_FILE_SIZE_LIMIT` があり、nginx 上限以下に保ってください。 | ||
|
|
||
| プラグインパッケージは `PLUGIN_MAX_PACKAGE_SIZE`（デフォルト 50 MB）を使い、同じ nginx 上限の対象です。詳細は [環境変数](/ja/self-host/deploy/configuration/environments#multi-modal-configuration) を参照してください。 |
Comment on lines
152
to
153
| docker exec -it docker-db-1 sh -c "echo 'host all all 172.19.0.0/16 trust' >> /var/lib/postgresql/data/pgdata/pg_hba.conf" | ||
| docker-compose restart |
|
|
||
| 两处都要提高。若只提高 API 限制，nginx 会在 API 看到文件之前返回 **413**。图片、视频、音频上传各自有 `UPLOAD_*_FILE_SIZE_LIMIT`，同样须不超过 nginx 上限。 | ||
|
|
||
| 插件包使用 `PLUGIN_MAX_PACKAGE_SIZE`（默认 50 MB），并受同一 nginx 上限约束。详见 [环境变量](/zh/self-host/deploy/configuration/environments#multi-modal-configuration)。 |
Comment on lines
143
to
147
| 如果你看到： | ||
| ``` | ||
|
|
||
| ```text | ||
| FATAL: no pg_hba.conf entry for host "172.19.0.7", user "postgres", database "dify", no encryption | ||
| ``` |
Author
|
Thanks for the review notes. Updated the zh/ja environment anchors to match the translated headings, unified the pg_hba snippet to |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Community Edition 1.17 operators hit failures that the current self-host troubleshooting pages do not cover, and one documented 502 recipe is harmful on current Compose.
This update extends the existing troubleshooting pages (en / zh / ja) against Dify
1.17.0(docker-compose.yaml,docker/.env.example,docker/envs/**, nginx templates, API/web entrypoints). No new nav page.What was missing
Invalid encrypted dataon plaintext); Console sessions need theaccess_tokencookie plusX-CSRF-Token; access cookies lastACCESS_TOKEN_EXPIRE_MINUTES(default 60);/installis first-time only; changingSECRET_KEYafter boot logs everyone out and breaks signed file URLs / OAuth credentials.docker/.envvsdocker/envs/*.env.example(required: false);api/worker/web/plugin_daemon/sandboxloadenv_file, while nginx / ssrf / weaviate / redis / db only see listedenvironment:interpolation. Recreate vs reload:NGINX_*needs nginx recreate becauseenvsubstruns at entrypoint; emptyCELERY_WORKER_AMOUNTbecomes concurrency 1.GUNICORN_TIMEOUTdefault 360 can kill long workflows while nginx proxy timeout is 3600s. Cross-linkTEXT_GENERATION_TIMEOUT_MSinstead of repeating it.apicontainer; no-egressapicannot install from Marketplace — upload a.difypkgvia Install from Local Package File. Installed in the UI is not the same asplugin_daemonlocal runtime ready. Failed tasks stay red until Clear all.PLUGIN_MAX_PACKAGE_SIZEandNGINX_CLIENT_MAX_BODY_SIZEmust move together (413)./socket.io/→api_websocket:5001; 502host not foundif that service is down.CONSOLE_API_URL: leaving it empty so the browser uses relative nginx is correct;http://api:5001is a browser footgun.UPLOAD_FILE_*must both match.Nginx 502 correction
The old recipe (replace
http://api:5001/http://web:3000with container IPs innginx/conf.d) is stale. 1.17 templates still use Compose DNS names andresolver 127.0.0.11 valid=30s. After recreatingapi/web, reload nginx. After changingNGINX_*, recreate nginx so the entrypoint re-runsenvsubst; reload does not.Verified against langgenius/dify tag
1.17.0.DEPLOYMENT_EDITIONstaysCOMMUNITY.Further reading on the pages points once to unofficial Community 1.17 checklists at https://github.com/kabishou11/dify-skills (not LangGenius).
Test plan
common-issuesanddocker-issuesin the docs previewdocker/.env.exampleanddocker-compose.yamlon the 1.17.0 tag