If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gdy666/lucky shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3mo ago
• 2 active contributors
• MIT licensed
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gdy666/lucky repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gdy666/lucky.

What it runs against: a local clone of gdy666/lucky — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gdy666/lucky | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 111 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gdy666/lucky. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gdy666/lucky.git
#   cd lucky
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gdy666/lucky and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gdy666/lucky(\\.git)?\\b" \\
  && ok "origin remote is gdy666/lucky" \\
  || miss "origin remote is not gdy666/lucky (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "module/service/service.go" \\
  && ok "module/service/service.go" \\
  || miss "missing critical file: module/service/service.go"
test -f "module/ddns/ddnscore.go" \\
  && ok "module/ddns/ddnscore.go" \\
  || miss "missing critical file: module/ddns/ddnscore.go"
test -f "module/portforward/portforward.go" \\
  && ok "module/portforward/portforward.go" \\
  || miss "missing critical file: module/portforward/portforward.go"
test -f "module/reverseproxy/reverseproxy.go" \\
  && ok "module/reverseproxy/reverseproxy.go" \\
  || miss "missing critical file: module/reverseproxy/reverseproxy.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 111 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~81d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gdy666/lucky"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Lucky is a lightweight Golang-based network utility for Linux embedded devices (routers, NAS, etc.) that provides IPv6-to-IPv4 port forwarding, reverse proxy, DDNS (with 20+ provider integrations), WoL, STUN NAT traversal, scheduled cron tasks, ACME certificate automation, and network storage mounting. It replaces complex tools like socat and nginx on resource-constrained hardware while exposing internal services to the public internet securely. Monolithic single-binary project structured as config module (config/*.go handles parsing), DDNS submodule (ddns/ and module/ddns/ with provider plugins), core port-forwarding/proxy logic, and a Gin-based REST API backend paired with a Vue3.2 frontend (not shown in file list). Main entry point is main.go with config files stored in ./config directory.

Home lab enthusiasts and OpenWrt users who need to expose internal services (game servers, media apps, databases) to the internet from behind ISP-level NAT without a public IPv4, and system administrators managing small routers or NAS devices who want a single UI to handle port forwarding, DDNS, and certificate renewal instead of shell scripts.

Actively developed but source-frozen at v1.4.10; the author explicitly states no further open-source updates are planned. The codebase is production-ready (used in real routers and NAS devices) with a working web UI and multiple provider integrations, but lacks visible CI/CD pipelines or automated tests in the provided file list, and the single-maintainer model increases risk of stagnation.

Critical single-maintainer risk with announced source freeze means no security patches beyond v1.4.10. Dependencies are relatively light (Gin, logrus, miekg/dns, gopsutil) and appear stable, but the lack of visible test coverage, CI/CD setup, or issue tracker visibility makes assessing bug backlog impossible. The architecture spans multiple semi-independent modules (DDNS providers, port forwarding, reverse proxy) which could harbor subtle integration bugs.

The project is in maintenance mode; no active development is listed in the README and the author explicitly halted open-source contributions after v1.4.10. The last mentioned work includes integrating Tencent EdgeOne CDN sponsorship for distribution, but commit activity and open issues are not visible in provided metadata.

Clone the repo with git clone https://github.com/gdy666/lucky.git && cd lucky. Compile with go build -o lucky main.go (requires Go 1.18+). Documentation is at https://lucky666.cn (Chinese); refer to the README for Docker usage or one-click installation scripts in https://github.com/gdy666/lucky-files.

Daily commands: Run ./lucky (prebuilt binary) or go build -o lucky main.go && ./lucky. The app listens on a configurable HTTP port (default likely 8888 based on typical Lucky deployments) and reads configuration from ./config/*.json files. Docker: docker run gdy666/lucky (see Dockerfile for build context).

• main.go — Application entry point; initializes all modules (DDNS, port forward, reverse proxy, WOL, SSL) and starts the HTTP server.
• module/service/service.go — Central service manager that orchestrates lifecycle of all feature modules; critical for understanding module initialization and runtime control.
• module/ddns/ddnscore.go — Core DDNS engine handling domain synchronization across multiple DNS providers; largest stateful component in the system.
• module/portforward/portforward.go — Port forwarding orchestrator managing TCP/UDP proxies; implements the primary use case of IPv6↔IPv4 translation.
• module/reverseproxy/reverseproxy.go — HTTP reverse proxy implementation; handles request routing and SSL termination.
• config/config.go — Central configuration loader and manager; all modules depend on this for runtime settings.
• go.mod — Dependency manifest; reveals core frameworks (Gin, logrus, DNS libraries) and version constraints.

Add a New DDNS Provider

1. Create new provider struct implementing the Provider interface (UpdateDomain, GetIP, etc.) in module/ddns/providers/ (module/ddns/providers/newprovider.go)
2. Register provider factory in module/ddns/providers/provider.go GetProvider() function (module/ddns/providers/provider.go)
3. Add provider-specific config fields to module/ddns/conf/ddns.go TaskConf struct (module/ddns/conf/ddns.go)
4. Update config schema documentation and web UI will auto-discover via service.GetDdnsManager() (config/ddns.go)

Add a New Port Forward Rule Type

1. Extend module/portforward/conf/portforward.go with new rule configuration fields (module/portforward/conf/portforward.go)
2. Modify module/portforward/socketproxy/baseproxyconf.go to parse and validate new rule type (module/portforward/socketproxy/baseproxyconf.go)
3. Create handler in module/portforward/socketproxy/ (tcpproxy.go or udpproxy.go) to implement proxy logic for new type (module/portforward/socketproxy/tcpproxy.go)
4. Register new rule type in module/portforward/portforward.go Start() method loop (module/portforward/portforward.go)

Add a New HTTP API Endpoint

1. Create handler function in relevant module's httpapi/ subdirectory (e.g., module/wol/httpapi/api.go) (module/wol/httpapi/api.go)
2. Register route in module's initialization code using gin.Engine.POST/GET/PUT pattern (module/wol/module.go)
3. Bind config changes to service manager via module/service/service.go event channels if async reload needed (module/service/service.go)
4. Add API documentation in README.md and test endpoint via curl or web UI integration (README.md)

Add a New Security Rule (Blacklist/Whitelist)

1. Define rule config struct in module/safe/conf/ (black.go or white.go) (module/safe/conf/black.go)
2. Implement rule matching logic in module/safe/blacklist.go or module/safe/whitelist.go (module/safe/blacklist.go)
3. Register rule check in module/safe/safecheck.go IsAllowed() function, called by proxy modules (module/safe/safecheck.go)
4. Wire rule configuration loading in config/blacklist.go or config/whitelist.go (config/blacklist.go)

• Go (Golang) — Single compiled binary deployable on embedded Linux; minimal memory footprint for routers; goroutines enable thousands of concurrent connections without thread overhead
• Gin (HTTP Framework) — Lightweight, fast HTTP router for the management UI and REST API; zero-allocation routing suitable for embedded devices
• miekg/dns library — Pure Go DNS client; enables DDNS updates without external tools; supports multiple DNS providers through modular architecture
• sirupsen/logrus — Structured logging across all modules; essential for debugging complex port forward and proxy rules on remote devices
• fatedier/golib — Proven networking utilities from FRP (fast reverse proxy) project; TCP/UDP proxy primitives
• eclipse/paho.mqtt.golang — Enables MQTT notifications for DDNS events and system status; IoT integration for home automation workflows

Config persistence: Rules are stored as JSON files in ./config/ and parsed at startup; in-memory modifications via API require explicit save-to-disk calls or they are lost on restart. DDNS caching: The cache.go module in ddnscore.go caches IP addresses to avoid hammering DNS providers; stale cache can mask real IP changes for minutes. Provider rate limits: Each DNS provider (Cloudflare, Aliyun, etc.) has different API rate limits and auth methods; misconfiguration silently fails in background tasks. NAT/STUN limitations: STUN traversal only works on NAT1 (ISP-level), not carrier-grade NAT (CGN); mode is silently skipped with no user warning. Platform quirks: WoL (Wake-on-LAN) and system metric collection (gopsutil) behave differently on Windows vs. Linux; cross-platform testing is minimal.

• IPv6-to-IPv4 Port Translation (NAT64-like) — Lucky's core feature solves the asymmetry of IPv6-only public connectivity to IPv4-only internal services; understanding source IP rewriting and connection tracking is essential for debugging port forwarding issues
• STUN (Session Traversal Utilities for NAT) — Lucky uses STUN protocol to detect public IP and NAT type for traversal; comprehending STUN's role vs. TURN and manual port forwarding clarifies when Lucky can/cannot pierce restrictive NAT (e.g., CGN)
• Whitelist vs. Blacklist Security Modes — Each port forwarding rule in config/portforward.go supports toggling between whitelist (only allow IPs in list) and blacklist (deny IPs in list) modes; misunderstanding the semantic inverts port security posture
• DDNS Provider Plugins — Lucky's architecture allows swapping DNS update backends (Aliyun, Cloudflare, etc.) without recompiling; each provider in ddns/*.go implements a plugin interface—critical for extending to custom DNS services
• ACME Certificate Automation with DNS Challenges — Lucky bundles ACME client (Let's Encrypt) with automatic DNS validation using integrated DDNS providers; this eliminates manual cert renewal and HTTP challenge infrastructure on port-forwarded services
• Cron-like Scheduling (Platform-Independent) — Lucky's scheduler module provides Cron syntax without OS-level cron dependency; critical for Windows-based NAS or routers that lack standard Cron, enabling scheduled rule toggles and task automation
• Reverse Proxy with HTTP Basic Auth & URL Rewriting — config/reverseproxy.go implements stateless HTTP proxying with optional Basic Auth headers and UserAgent filtering; understanding its layer-7 filtering helps avoid exposing unintended internal services

• fatedier/frp — Established Golang reverse proxy tunnel for NAT traversal; Lucky's STUN module solves a similar problem for IPv6-first networks with lighter footprint
• acmesh-official/acme.sh — Bash-based ACME cert automation; Lucky integrates equivalent functionality with DDNS provider auto-discovery for single-tool certificate + DNS management
• jeessy2/ddns-go — Go DDNS client supporting similar providers (Aliyun, Cloudflare, DNSPod); Lucky extends this pattern with port forwarding and reverse proxy in one binary
• gdy666/lucky-files — Official Lucky installation scripts and package repository; companion repo containing one-click installers, OpenWrt IPK builds, and Docker images for Lucky
• openwrt/openwrt — Target platform for Lucky; many deployments run as an OpenWrt package to add advanced networking features to consumer routers without custom firmware

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Refactor duplicate DDNS provider logic into shared base implementation

The repo has DDNS providers duplicated in two locations (ddns/ and module/ddns/providers/) with nearly identical implementations (alidns.go, baidu.go, cloudflare.go, dnspod.go, godaddy.go, huawei.go, porkbun.go). This creates maintenance burden and inconsistency. Extract common provider logic into a base struct/interface in module/ddns/providers/provider.go to reduce ~70% code duplication across these 7 provider files.

• [ ] Analyze common patterns in ddns/alidns.go, ddns/baidu.go, ddns/cloudflare.go, etc. versus module/ddns/providers/ equivalents
• [ ] Extend module/ddns/providers/provider.go to define a shared BaseProvider struct with common authentication, request, and response handling methods
• [ ] Refactor each provider in module/ddns/providers/ to embed BaseProvider and override only provider-specific logic
• [ ] Remove or deprecate duplicate implementations in ddns/ directory
• [ ] Add integration tests in module/ddns/providers/ to verify all 7 providers work after refactoring

Add unit tests for port forwarding proxy implementations

The module/portforward/socketproxy/ package contains critical proxy logic (tcpproxy.go, udpproxy.go, socketproxy.go) but has no visible test files. TCP/UDP proxy correctness is essential for the core functionality. Add comprehensive tests covering edge cases like connection timeouts, packet fragmentation, and concurrent connections.

• [ ] Create module/portforward/socketproxy/socketproxy_test.go with tests for BaseProxyConf validation and initialization
• [ ] Create module/portforward/socketproxy/tcpproxy_test.go testing TCP connection forwarding, error handling, and connection cleanup
• [ ] Create module/portforward/socketproxy/udpproxy_test.go testing UDP packet forwarding, timeout behavior, and memory cleanup
• [ ] Add benchmarks in *_test.go files to track performance of proxy operations
• [ ] Document test coverage in a TESTING.md file referencing specific test scenarios

Create comprehensive GitHub Actions CI workflow with Go linting and security scanning

The repo lacks visible CI/CD configuration (.github/workflows/ not in file list). For a security-sensitive tool handling port forwarding and DNS, automated linting, testing, and vulnerability scanning is critical. Add a workflow that runs on PR/push to catch issues before merge.

• [ ] Create .github/workflows/go-test.yml to run 'go test ./...' across all packages including module/ddns/, module/portforward/, module/reverseproxy/
• [ ] Add golangci-lint step to check code quality against rules relevant to network code (e.g., error handling, unused code)
• [ ] Integrate gosec for security vulnerability scanning on all Go files
• [ ] Add go mod tidy check to prevent dependency drift
• [ ] Configure workflow to fail on test failures, lint warnings (set to error level), and any security findings, with clear failure messages

• Add unit tests for config/ parsing: Create test files (e.g., config/config_test.go, config/portforward_test.go) to verify JSON unmarshalling and validation of port forwarding rules, DDNS config, and whitelist/blacklist modes; currently no visible test coverage.
• Document DDNS provider setup: Write provider-specific guides in docs/providers/ for each of the 20+ integrated DNS services (Aliyun, Cloudflare, GoDaddy, etc.) showing exact API key retrieval and config JSON examples; README only lists provider names without setup steps.
• Add request/response logging to reverse proxy module: Extend config/reverseproxy.go to log HTTP headers, response codes, and latency for each proxied request (similar to port forwarding's access logs in config/portforward.go) to help users debug proxy rules.

• High · Outdated Dependencies with Known Vulnerabilities — go.mod. Multiple dependencies are significantly outdated and likely contain known security vulnerabilities. Notable examples: golang.org/x/net v0.0.0-20221004 (from 2022), golang.org/x/crypto v0.0.0-20221010 (from 2022), and github.com/gin-gonic/gin v1.8.1 (2022). These versions are 2+ years old and have numerous CVEs patched in newer releases. Fix: Execute 'go get -u ./...' to update all dependencies to their latest versions. Specifically update: golang.org/x/net, golang.org/x/crypto, golang.org/x/sys, gin-gonic/gin, and miekg/dns to current stable versions.
• High · Exposed Network Port Without Security Controls — Dockerfile, EXPOSE 16601. Port 16601 is exposed in the Dockerfile without any documented security mechanism. Given this is a routing/proxy application handling port forwarding and reverse proxies, this port likely requires authentication and encryption controls that are not evident from the infrastructure configuration. Fix: Implement TLS/SSL encryption for all exposed ports. Add mandatory authentication (JWT token validation is present in dependencies but needs verification of enforcement). Document port security requirements. Consider using a reverse proxy with authentication in front of the application.
• High · Weak JWT Implementation — go.mod, github.com/golang-jwt/jwt dependency. Dependency github.com/golang-jwt/jwt v3.2.2+incompatible is used, which is an older and deprecated version. The 'incompatible' tag indicates potential compatibility issues and lack of proper versioning. This is critical for an application exposing network services. Fix: Upgrade to github.com/golang-jwt/jwt/v5 (current stable version). Ensure JWT secrets are not hardcoded and use strong key management. Validate token expiration and implement token refresh mechanisms.
• Medium · Missing Security Headers Configuration — module/weblog/weblog.go, main.go (inferred). Using Gin framework with no visible security header middleware configuration. The gzip middleware is present but no CORS, CSP, X-Frame-Options, or other security headers are documented in the visible configuration. Fix: Implement security middleware for: Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security. Use gin-contrib/secure or similar middleware. Configure CORS with explicit allowed origins rather than wildcards.
• Medium · Docker Image Built from Scratch Without Base Security — Dockerfile. Multi-stage builds or security scanning are not evident. Building from 'scratch' with a single binary provides minimal attack surface but also means no security updates to base libraries are possible. No health checks or security context specifications are visible. Fix: Add HEALTHCHECK directive to Dockerfile. Document and enforce non-root user execution. Consider using distroless or minimal base images instead of scratch for maintainability. Add security scanning in build pipeline (Trivy, Snyk).
• Medium · Configuration File Path Hardcoding — Dockerfile, CMD ['-c', '/goodluck/lucky.conf']. Default configuration path /goodluck/lucky.conf is hardcoded in Dockerfile CMD. No environment variable override is visible, reducing flexibility and potentially creating security issues if configurations contain sensitive data. Fix: Use environment variables for configuration paths: CMD ['/lucky', '-c', '${CONFIG_PATH:-/goodluck/lucky.conf}']. Ensure configuration files are not world-readable and contain proper file permissions validation.
• Medium · Unclear Input Validation on Network Services — module/ddns/, module/portforward/, module/reverseproxy/. Application handles multiple network protocols (IPv4/IPv6 port forwarding, reverse proxies, DNS). No evident input validation framework visible in structure. DNS parsing via github.com/miekg/dns could be vulnerable to crafted DNS packets without proper validation. Fix: Implement comprehensive input validation for all external data sources. For DNS: validate packet structure and size limits. For port forwarding: validate port ranges (1-65535), IP addresses, and protocol specifications. Implement rate limiting.
• Medium · MQTT Dependency — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.