add cloudflare and documentation

docs/CONFIGURATION.md

@@ -0,0 +1,86 @@
+**SafelineAPI Configuration and Cloudflare DNS Guide**
+
+This guide explains how to configure SafelineAPI to use Cloudflare for DNS-01 challenges and how to run the program.
+
+**Quick Start**
+- **Prerequisites:** Go is only required for building from source. If you prefer, use the built binary produced by `go build`.
+- **Minimal steps:** create a Cloudflare API token, update `config.json`, and run the program.
+
+**Config File Location**
+- The primary configuration file is `config.json` in the repository root. See `docs/cloudflare.md` for a short Cloudflare-specific note.
+
+**Important fields**
+- **SafeLine.ApiToken:** API token used to connect to the SafeLine API.
+- **ApplyCert.Email:** Contact email used when requesting certificates.
+- **ApplyCert.DNSProviderConfig.DNSProvider:** Set this to `Cloudflare` to use Cloudflare.
+- **ApplyCert.DNSProviderConfig.Cloudflare.APIToken:** Recommended — a scoped Cloudflare API Token with `Zone:DNS:Edit` on your zone(s).
+- **ApplyCert.DNSProviderConfig.Cloudflare.APIKey** and **Email:** Optional — use only if you must authenticate with the Global API key.
+
+**Example `config.json` snippet**
+
+```json
+{
+  "SafeLine": {
+    "Host": { "HostName": "192.168.1.4", "Port": "1443" },
+    "ApiToken": "<your-safeline-api-token>"
+  },
+  "ApplyCert": {
+    "Days": 30,
+    "Email": "you@example.com",
+    "SavePath": "C:/path/to/ssl",
+    "DNSProviderConfig": {
+      "DNSProvider": "Cloudflare",
+      "Cloudflare": {
+        "APIToken": "<your-cloudflare-scoped-token>"
+      }
+    }
+  }
+}
+```
+
+**Create a Cloudflare API Token**
+1. Log into the Cloudflare dashboard and open **My Profile → API Tokens**.
+2. Click **Create Token** and choose the **Edit zone DNS** template or set custom permissions:
+   - Zone:Zone:Read
+   - Zone:DNS:Edit
+3. Scope the token to the specific zone(s) you need and create the token.
+4. Put the token value in `ApplyCert.DNSProviderConfig.Cloudflare.APIToken`.
+
+**Run commands**
+- Build the binary (optional):
+```powershell
+cd C:\Users\samge\coding\SafelineAPI-1
+go build -o safelineApi.exe ./cmd/safelineApi
+```
+- Run with the built binary:
+```powershell
+.\safelineApi.exe
+```
+- Or run directly with Go:
+```powershell
+go run ./cmd/safelineApi -- -t "<SafeLineApiToken>" -D "Cloudflare" -e "you@example.com"
+```
+
+Notes on flags: the project reads flags and `config.json`. If a flag is present it will be used for that run.
+
+**Troubleshooting**
+- Warning about missing values: If you see warnings like `未设置 DNS服务提供商`, set `ApplyCert.DNSProviderConfig.DNSProvider` or pass `-D` on the command line.
+- Dependency/download issues: If `go build` stalls on module downloads, try setting a proxy:
+```powershell
+go env -w GOPROXY=https://goproxy.cn,direct
+go clean -modcache
+go mod tidy
+go build -v ./...
+```
+- Cloudflare auth mismatch: Use `APIToken` (recommended). If using `APIKey` (global key), also provide the account `Email`.
+
+**Security recommendations**
+- Prefer scoped API tokens over the global API key.
+- Store secrets outside source control. Use environment variables or an external secret store in production.
+- Limit token scope to required zones.
+
+**Files added/edited**
+- Documentation: [docs/cloudflare.md](docs/cloudflare.md)
+- Configuration example: `config.json` at project root
+
+If you'd like, I can also add a short `README.md` or copy a minimal example `config.example.json` to the repo root for easy onboarding. Which would you prefer next?

docs/cloudflare.md

@@ -0,0 +1,42 @@
+# Cloudflare DNS provider
+
+This project supports using Cloudflare for the DNS-01 challenge via the lego DNS provider.
+
+Supported config fields (in `config.json` under `ApplyCert.DNSProviderConfig`):
+
+- `DNSProvider`: set to `Cloudflare`
+- `Cloudflare.APIToken`: Recommended — create a scoped API Token in Cloudflare (Zone.DNS edit).
+- `Cloudflare.APIKey`: Optional — Global API Key (not recommended when token available).
+- `Cloudflare.Email`: Optional — account email (used with Global API Key if needed).
+
+Example `config.json` snippet:
+
+{
+  "ApplyCert": {
+    "DNSProviderConfig": {
+      "DNSProvider": "Cloudflare",
+      "Cloudflare": {
+        "APIToken": "your-cloudflare-api-token",
+        "APIKey": "optional-global-api-key",
+        "Email": "you@example.com"
+      }
+    }
+  }
+}
+
+How to create a Cloudflare API token
+
+1. Log into the Cloudflare dashboard.
+2. Visit "My Profile" → "API Tokens" → "Create Token".
+3. Use the "Edit zone DNS" template or create a custom token with the following permissions scoped to your zone(s):
+   - Zone:Zone:Read
+   - Zone:DNS:Edit
+4. Save the token and put it into `Cloudflare.APIToken`.
+
+Notes and links
+
+- The integration uses the lego v4 Cloudflare provider.
+- Cloudflare API docs: https://developers.cloudflare.com/api/
+- Certbot cloudflare plugin docs (useful for end users): https://certbot-dns-cloudflare.readthedocs.io/en/stable/
+
+If you want, I can run `go build` and fix any compile errors from these changes, or adjust field names to match the exact lego provider struct names on your machine. Would you like me to build and test now?