Harden security: Switch to non-root user and sanitize error responses

[RinZ27]

Caught a couple of low-hanging security issues while poking around the admin routes and Docker setup.

First, the production Docker image was running as root. I've added a dedicated ragflow user and updated the permissions so we're not handing out root access by default—standard practice to minimize the blast radius if anything goes wrong.

Second, I noticed we were piping raw exception strings (str(e)) directly back to the client in several admin routes. That's a bit risky since it can leak internal paths or stack traces. I've sanitized those to return a generic "Internal Server Error" while keeping the AdminException messages intact since those seem intended for the user.

Let me know if this looks good to you guys!

[KevinHuSh]

Appreciations!
CI failure.

[Lynn-Inf]

Great PR, thank you!
One small suggestion to make the error handling even more robust: while returning a generic message to the client is perfect, could we also log the full exception (with traceback) using logging.error on the server side? This will be invaluable for debugging without exposing any details to the end user.

[Lynn-Inf]

To pass the Ruff check, you can log the exception locally before returning. For example, adding logging.error(str(e)) where the e variable is already in scope will satisfy the linter while preserving our error handling logic.

[RinZ27]

Thanks for the thorough review. I've updated the PR to address the security and logging concerns.

Key changes:

1. Exception Logging: All except Exception blocks in admin/server/routes.py now use logging.exception(e). This ensures we capture the full stack trace on the server for debugging while returning a sanitized "Internal Server Error" to the client. This also resolves the Ruff unused variable warning.
2. Docker Permissions: Refined the Dockerfile to use --chown during the COPY stage. This ensures the ragflow user has correct ownership from the start and prevents potential permission issues with the entrypoint script.

Let me know if there's anything else that needs attention.

[RinZ27]

@Lynn-Inf @KevinHuSh Just a quick heads-up: I've implemented the server-side logging and refined the Docker permissions as discussed. The CI should be back to green now. Mind taking another look when you have a moment? Thanks!

[asiroliu]

@RinZ27
The RAGFlow server failed to start properly.

[docling] disabled by USE_DOCLING
Starting nginx...
2026/01/06 10:12:19 [warn] 9#9: the "user" directive makes sense only if the master process runs with super-user privileges, ignored in /etc/nginx/nginx.conf:1
2026/01/06 10:12:19 [emerg] 9#9: mkdir() "/var/lib/nginx/body" failed (13: Permission denied)
[docling] disabled by USE_DOCLING
Starting nginx...
2026/01/06 10:12:19 [warn] 9#9: the "user" directive makes sense only if the master process runs with super-user privileges, ignored in /etc/nginx/nginx.conf:1
2026/01/06 10:12:19 [emerg] 9#9: mkdir() "/var/lib/nginx/body" failed (13: Permission denied)

[Lynn-Inf]

LGTM on the error handling changes. For the Dockerfile user changes, my colleague @asiroliu will take a look and help out.

[RinZ27]

Thanks @Lynn-Inf and @asiroliu for the review and for catching the Nginx permission issue!

I'm glad the error handling part is merged. Regarding the Docker non-root user changes, I understand why it was reverted to keep the build stable. The Nginx permission error (/var/lib/nginx/body) is a common hurdle when switching to non-root.

If you're still interested in hardening the container security, I can open a separate PR to address just the Dockerfile changes. I'll make sure to adjust the Nginx configuration and directory permissions (e.g., chown the necessary Nginx paths) so it runs smoothly as the ragflow user. Let me know if you'd like me to proceed with that!

[Lynn-Inf]

This is fantastic to hear, thank you for your understanding and continued initiative! We greatly appreciate you offering to see this through.

To keep the changes consolidated, could you please update the original PR/branch with the refined non-root user setup? Your approach of properly adjusting Nginx configurations and directory permissions (like chown for /var/lib/nginx/) is exactly right. Once both the error handling and the updated user change are ready in the same PR, we'll be happy to merge them together as a complete security improvement.

Please feel free to push the additional commits to the existing branch. We'll review the entire set once you signal it's ready. Thanks again for driving this!

[RinZ27]

Thanks @Lynn-Inf, good call on the Nginx permissions.

I've updated the PR to include the non-root fixes. Switched Nginx to listen on 8080/8443 and moved the PID file to /tmp to avoid the root requirement. I also added the necessary chown steps in the Dockerfile for the log and cache directories.

Compose configs are updated to map to the new internal ports. CI should be happy now.

[Lynn-Inf]

Something went wrong in CI. It seems that ragflow service can't find packages in venv.

Traceback (most recent call last):
  File "/ragflow/rag/svr/task_executor.py", line 26, in <module>
    from api.db import PIPELINE_SPECIAL_PROGRESS_FREEZE_TASK_TYPES
  File "/ragflow/api/db/__init__.py", line 18, in <module>
    from strenum import StrEnum
ModuleNotFoundError: No module named 'strenum'
Traceback (most recent call last):
  File "/ragflow/rag/svr/sync_data_source.py", line 35, in <module>
    from flask import json
ModuleNotFoundError: No module named 'flask'
Traceback (most recent call last):
  File "/ragflow/admin/server/admin_server.py", line 25, in <module>
    from flask import Flask
ModuleNotFoundError: No module named 'flask'
Traceback (most recent call last):
  File "/ragflow/api/ragflow_server.py", line 22, in <module>
    from plugin import GlobalPluginManager
  File "/ragflow/plugin/__init__.py", line 1, in <module>
    from .plugin_manager import PluginManager
  File "/ragflow/plugin/plugin_manager.py", line 4, in <module>
    import pluginlib
ModuleNotFoundError: No module named 'pluginlib'

[RinZ27]

Thanks @Lynn-Inf for the feedback. It looks like the switch to the non-root user is causing issues with locating the packages in the virtual environment. I'll investigate the PATH/permission setup and push a fix.

[RinZ27]

I've pushed a fix for the ModuleNotFoundError and potential permission issues.

The root cause was that uv was installing the Python interpreter in /root/.local/share/uv, which is inaccessible to the ragflow user. This caused the virtual environment symlinks to fail, leading the system to fallback to the system Python (which lacks the required dependencies like strenum).

Changes:

1. Dockerfile:
   • Set UV_PYTHON_INSTALL_DIR=/usr/local/share/uv/python to ensure the Python interpreter is installed in a globally accessible location.
   • Moved nltk_data to /usr/share/nltk_data and set the NLTK_DATA environment variable for runtime accessibility.
   • Cleaned up unused /root/.ragflow creation in the base stage.
2. entrypoint.sh:
   • Made LD_LIBRARY_PATH architecture-independent using uname -m (fixing potential ARM64 issues).
   • Explicitly pointed PY to the virtual environment's Python interpreter to ensure the correct environment is always used.
   • Updated ensure_docling to use the same Python interpreter.

This should get the CI back to green and ensure the services can find their packages when running as the ragflow user.

[asiroliu]

@RinZ27

Traceback (most recent call last):
  File "/ragflow/admin/server/admin_server.py", line 30, in <module>
    from routes import admin_bp
  File "/ragflow/admin/server/routes.py", line 24, in <module>
    from services import UserMgr, ServiceMgr, UserServiceMgr, SettingsMgr, ConfigMgr, EnvironmentsMgr
  File "/ragflow/admin/server/services.py", line 23, in <module>
    from api.db.joint_services.user_account_service import create_new_user, delete_user_data
  File "/ragflow/api/db/joint_services/user_account_service.py", line 22, in <module>
    from api.db.services.canvas_service import UserCanvasService
  File "/ragflow/api/db/services/canvas_service.py", line 20, in <module>
    from agent.canvas import Canvas
  File "/ragflow/agent/canvas.py", line 29, in <module>
    from agent.component import component_class
  File "/ragflow/agent/component/__init__.py", line 44, in <module>
    _import_submodules()
  File "/ragflow/agent/component/__init__.py", line 32, in _import_submodules
    module = importlib.import_module(f".{module_name}", package=__name__)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/ragflow/agent/component/agent_with_tools.py", line 27, in <module>
    from agent.tools.base import LLMToolPluginCallSession, ToolParamBase, ToolBase, ToolMeta
  File "/ragflow/agent/tools/__init__.py", line 44, in <module>
    _import_submodules()
  File "/ragflow/agent/tools/__init__.py", line 32, in _import_submodules
    module = importlib.import_module(f".{module_name}", package=__name__)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/ragflow/agent/tools/crawler.py", line 18, in <module>
    from crawl4ai import AsyncWebCrawler
  File "/ragflow/.venv/lib/python3.12/site-packages/crawl4ai/__init__.py", line 3, in <module>
    from .async_webcrawler import AsyncWebCrawler, CacheMode
  File "/ragflow/.venv/lib/python3.12/site-packages/crawl4ai/async_webcrawler.py", line 13, in <module>
    from .async_database import async_db_manager
  File "/ragflow/.venv/lib/python3.12/site-packages/crawl4ai/async_database.py", line 22, in <module>
    os.makedirs(DB_PATH, exist_ok=True)
  File "<frozen os>", line 225, in makedirs
PermissionError: [Errno 13] Permission denied: '/root/.crawl4ai'

[RinZ27]

I've pushed another fix to address the Permission denied: '/root/.crawl4ai' error.

The issue was that sudo -u ragflow doesn't automatically update the HOME environment variable to the target user's home directory by default (it often preserves /root). This caused libraries like crawl4ai to attempt writing to /root, which is forbidden for the ragflow user.

Fix:

• Updated docker/entrypoint.sh to explicitly pass HOME=/home/ragflow in all sudo commands that execute Python scripts.

This ensures that the application correctly resolves ~ to /home/ragflow, which is writable by the user. CI should hopefully be happy this time!

[RinZ27]

Resolved the latest merge conflict in docker/entrypoint.sh.

The upstream main branch switched to using uv pip install for docling. I've updated the entrypoint to adopt this change while wrapping the command in sudo -u ragflow ... (with HOME set correctly) to ensure it runs securely as the non-root user and installs into the correct environment.

[RinZ27]

I've updated docker/entrypoint.sh to be more robust against sudo's environment handling.

Instead of relying on sudo variable assignment (which can be tricky when combined with --preserve-env depending on the sudo policy), I'm now using the env command inside the sudo shell to explicitly set HOME=/home/ragflow for the Python processes.

This guarantees that the process sees the correct home directory regardless of how sudo preserves or resets the environment. This should definitively fix the Permission denied error for crawl4ai and docling.

[RinZ27]

I've refactored docker/entrypoint.sh to use runuser instead of sudo for switching to the ragflow user.

Changes:

1. Replaced sudo -u ragflow with runuser -u ragflow --.
2. Explicitly setting HOME, PATH, PYTHONPATH, and VIRTUAL_ENV in the runuser command to ensure the Python environment and tools (like uv and docling) behave exactly as expected.
3. Using the absolute path for uv (/usr/local/bin/uv) and adding --python "$PY" to the install command to guarantee it targets the correct virtual environment.

This should bypass any potential sudo policy issues or environment sanitization that might have been causing the failures.

[RinZ27]

Hi @KevinHuSh @Lynn-Inf,

I've decided to close this PR for now.

After several attempts to harden the container by switching to a non-root user, it's clear that
the 'permission domino effect' in this environment is more complex than anticipated. The
interplay between host-mounted volumes (logs/cache), deep-nested AI library caches (uv, crawl4ai,
nltk), and the specific CI environment creates a high risk of instability.

I sincerely apologize for the extensive commit history and for consuming so much of your CI
resources during this process. Transitioning a production-grade system like RAGFlow from root to
non-root is a significant architectural shift, and doing so purely through CI iterations without
a identical local replication environment is proving to be counterproductive.

I'd rather close this now to keep your project history clean and avoid further noise. I may
revisit this in the future with a more isolated and pre-validated approach.

Thank you for your patience and the thorough reviews. Best of luck with the release!