A lazy developer's solution for home server management, featuring dynamic DDNS (Aliyun DNS API) and automatic port mapping via UPnP.

• Dynamic DDNS: Automatically update DNS records using Aliyun DNS API, support for multiple domains, real-time public IP sync, and custom record types.
• UPnP Port Mapping: Automatically register port mappings to your router, support TCP/UDP, dynamic port management, and real-time status monitoring.
• Web UI: Modern, responsive, and supports both English and Chinese.
• Multi-language: Switch between English and Chinese easily.

• Frontend: Next.js 15 (App Router), TypeScript, Tailwind CSS 4, shadcn/ui, next-intl
• Backend: FastAPI (Python 3.12+), SQLAlchemy, miniupnpc, Aliyun DNS SDK

git clone https://github.com/yfge/PandaHome.git
cd PandaHome

# Backend (run from repository root)
uv pip install --system -e api
# or
pip install -e api

# Frontend
npm install --prefix web

cp api/.env.example api/.env
cp web/.env.local.example web/.env.local

Then edit the files to provide your secrets (see Environment Variables).

# From repository root
pip install pre-commit
pre-commit install --install-hooks

cd api
alembic upgrade head
bootstrap-admin --username admin --password changeme --email admin@example.com

# Backend (port 8003 to match the web client default)
uvicorn src.app.main:app --reload --app-dir api/src --port 8003

# Frontend
npm run dev --prefix web

• Web UI: http://localhost:3000
• API Docs: http://localhost:8003/docs

• Log every code-producing session in agent_chats/YYYYMMDD-HHMMSS-topic.md following the template described in agent_chats/README.md.
• Run tests before opening a PR:
  • pytest -q api/tests
  • npm run test --prefix web
• Run pre-commit run --all-files before opening a PR; hooks enforce Ruff lint/format on api/, npm run lint (and tests) for the frontend when dependencies are installed.
• See AGENTS.md for the full engineering handbook covering repository layout, conventions, and incident process.

Backend (api/.env):

Frontend (web/.env.local):

1. Seed an administrator with bootstrap-admin --username admin --password changeme --email admin@example.com (re-run to rotate credentials).
2. Start backend + frontend, then visit http://localhost:3000/login to sign in.
3. Successful login stores a bearer token locally; protected routes (/status, /upnp, /domains) require the token.
4. Expired or invalid tokens trigger automatic logout and redirect back to /login.

See docs/auth-lifecycle.md for the full authentication lifecycle (env requirements, CLI bootstrap, login/logout flow).

• GET /api/status - System status snapshot
• GET /health - Health check

See docs/monitoring.md for data sources, update cadence, and troubleshooting tips.

• GET /api/upnp/mappings - List all port mappings
• POST /api/upnp/mappings - Add a new port mapping
• DELETE /api/upnp/mappings/{external_port}?protocol=TCP|UDP - Remove a port mapping (defaults to TCP)

See docs/upnp.md for router prerequisites, troubleshooting tips, and security notes.

• GET /api/domains/domains - List all domains
• GET /api/domains/domains/{domain}/records - List domain records
• POST /api/domains/domains/{domain}/records - Add a new record
• PUT /api/domains/domains/{domain}/records/{record_id} - Update a record
• DELETE /api/domains/domains/{domain}/records/{record_id} - Delete a record

See docs/domains.md for Aliyun access key setup, required permissions, and rate limit troubleshooting.

MIT