05

July 24, 2026 · View on GitHub


Status	[ ] Draft \| [ ] In Review \| [ ] Approved
Version	0.4
Related PRD	Section 7 Non-Functional Requirements (Deployment, Security)

1. Environment Requirements | 环境要求

1.1 Runtime

Item	Requirement
Python	3.11+
OS	Linux (Recommended) / Windows Server / Container
Memory	Minimum 4GB, Recommended 8GB+ (for local LLM/Vector DB)
CPU	2+ Cores (AVX support for some vector libs)
Disk	SSD recommended for Vector DB I/O

1.2 Dependent Services

Service	Usage	Required
Vector DB	Knowledge Base retrieval (Chroma/Qdrant)	Yes
LLM Endpoint	OpenAI / Ollama / Claude / Qwen	Yes
Redis	Session/Cache (Optional for MVP)	Optional
PostgreSQL	Task/User data (Future)	Optional
AAD	Identity & SSO	Recommended for Prod

2. Deployment Options | 部署方式

2.1 One-Click Deployment (Recommended) | 一键部署（推荐）

Suitable for Development, PoC, or Small Teams. Includes API and optional Ollama.

# Clone repo
git clone https://github.com/arthurpanhku/DocSentinel.git
cd DocSentinel

# Run script
chmod +x deploy.sh
./deploy.sh

React Console: http://localhost:8000/console
API Docs: http://localhost:8000/api-docs

2.2 Docker Manual | 容器化手动部署

See Dockerfile and docker-compose.yml in repo.

Compose Example:

services:
  agent:
    build: .
    ports: ["8000:8000"]
    env_file: .env
    volumes: ["./data:/app/data"]

2.3 Python Standalone | Python 单机部署

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --host 0.0.0.0 --port 8000

2.4 Air-Gapped / Private Cloud | 内网/私有化

For environments without public internet access:

LLM: Use Ollama or vLLM deployed internally.
Identity: Use local accounts or internal IdP (LDAP/AD) if AAD is unreachable.
Dependencies: Mirror PyPI packages or use pre-built Docker images.

3. Verify Installation | 验证安装

3.1 Automated Verification (Recommended)

Run the integration test script to verify core functions (API, Skills, Orchestrator) in an isolated environment:

./test_integration.sh

3.2 Manual Check

After deployment, you can run a quick self-check using pytest (requires python environment):

# Install test deps
pip install -r requirements-dev.txt

# Run integration tests against your local instance (mocking LLM)
pytest tests/test_health.py tests/test_assessments_api.py

If you see PASSED, the core API and orchestration logic are working correctly.

4. Configuration Reference | 配置项清单

See .env.example for the template.

4.1 App & API

Variable	Description	Example
`ENV`	Environment	`production`
`LOG_LEVEL`	Logging level	`INFO`
`API_PREFIX`	API path prefix	`/api/v1`
`CORS_ORIGINS`	Comma-separated allowed browser origins	Local console origins
`SECRET_KEY`	Session/Sign key	Random String

4.2 Authentication (AAD)

Variable	Description
`AAD_TENANT_ID`	Azure Tenant ID
`AAD_CLIENT_ID`	App Client ID
`AAD_CLIENT_SECRET`	Client Secret
`AAD_REDIRECT_URI`	OIDC Callback

4.3 LLM Provider

Variable	Description	Example
`LLM_PROVIDER`	Backend choice	`openai` / `ollama`
`OPENAI_API_KEY`	Key for OpenAI	`sk-...`
`OLLAMA_BASE_URL`	Local LLM URL	`http://localhost:11434`
`OLLAMA_MODEL`	Model name	`llama3`

4.4 Vector Store

Variable	Description	Example
`CHROMA_PERSIST_DIR`	Data path	`./data/chroma`
`EMBEDDING_MODEL`	HuggingFace model	`all-MiniLM-L6-v2`

4.5 Limits

Variable	Description	Default
`UPLOAD_MAX_FILE_SIZE_MB`	Max file size	50
`UPLOAD_MAX_FILES`	Max files per req	10
`KB_REINDEX_ROOTS`	Server directories allowed for KB reindex	`./examples`
`MCP_DOCUMENT_ROOTS`	Directories accessible to MCP document tools	`./examples`
`AGENT_GATEWAY_ENABLED`	Enable remote MCP and A2A endpoints	`true`
`AGENT_GATEWAY_TOKEN`	Bearer token for remote agent access; empty means loopback-only	empty
`AGENT_GATEWAY_PUBLIC_URL`	Public base URL advertised by the A2A Agent Card	`http://localhost:8000`
`AGENT_GATEWAY_ALLOWED_HOSTS`	MCP Host allow-list; add the exact deployment host and port	local hosts
`AGENT_GATEWAY_ALLOWED_ORIGINS`	MCP browser Origin allow-list; add trusted web origins only	local origins
`AGENT_GATEWAY_TASK_TIMEOUT_SECONDS`	Compatibility MCP wait timeout	`300`

When running through Docker or a reverse proxy, configure AGENT_GATEWAY_TOKEN; forwarded traffic is not considered loopback.

4.6 Parser Engine

Variable	Description	Default
`PARSER_ENGINE`	`auto`, `docling`, or `legacy`	`auto`

4.7 Graph RAG (LightRAG)

Variable	Description	Default
`ENABLE_GRAPH_RAG`	Enable graph-based retrieval	`true`
`LIGHTRAG_WORKING_DIR`	LightRAG data directory	`./data/lightrag`
`GRAPH_RAG_QUERY_MODE`	Query mode: naive/local/global/hybrid	`hybrid`

4.8 Threat Evidence Critic

Variable	Description	Default
`EVIDENCE_CRITIC_ENABLED`	Run inference-time evidence verification for Design threats	`true`
`EVIDENCE_CRITIC_MAX_CANDIDATES`	Current-document passages supplied per threat	`5`
`EVIDENCE_CRITIC_MAX_THREATS`	Threats included in one verifier request	`20`

The critic never uses policy or assessment-history chunks as proof of a current design fact. If inference is unavailable or a returned evidence ID does not resolve to an allowed current-document passage, the affected threat is marked insufficient_evidence and remains subject to human review.

4.9 SSDLC Pipeline

Variable	Description	Default
`SSDLC_DEFAULT_STAGE`	Default SSDLC stage when not specified: `auto` or a specific stage name	`auto`

Valid stage values: requirements, design, development, testing, deployment, operations. When set to auto, the SSDLC Router attempts to detect the stage from document content.

5. Operations and Monitoring | 运维与监控

5.1 Health Checks

Liveness: GET /health (Returns 200 OK with version and environment info)
LLM Config: GET /config/llm (Shows current LLM provider and model)

5.2 Logging

Format: JSON or Text (Standard Output).
Privacy: Do not log sensitive document content or full user tokens.
Fields: Request ID, User ID, Task ID, Duration, Error Stack.

5.3 Auditing

Scope: Who initiated assessment? Who accessed reports?
Retention: Comply with organization policy (e.g. 90 days).

5.4 Backup

Vector DB: Backup the CHROMA_PERSIST_DIR regularly.
Config: Backup .env (securely).

6. Troubleshooting | 常见问题排错

Issue	Possible Cause	Suggestion
Login Loop / 401	AAD Config mismatch	Check Client ID, Secret, and Redirect URI in Azure Portal.
Task Pending Forever	Worker stuck / LLM timeout	Check logs for LLM connection errors or parser hangs.
Empty KB Results	Embeddings mismatch	Ensure ingestion and query use the same embedding model.
ServiceNow Error	Network / Auth	Verify instance URL reachability and credentials.

7. Changelog | 修订记录

Version	Date	Changes
0.4	2026-03	Added SSDLC Pipeline config section.
0.3	2026-03	Removed Streamlit references. Added Parser Engine and Graph RAG config sections. Fixed section numbering. Updated health check endpoints.
0.2	2025-03	Added Docker Compose and standalone deployment options.
0.1	Initial	Draft Deployment and Runbook.