{"id":15658775,"url":"https://github.com/database64128/shadowsocks-uri-generator","last_synced_at":"2025-10-03T15:45:45.289Z","repository":{"id":37090635,"uuid":"273852882","full_name":"database64128/shadowsocks-uri-generator","owner":"database64128","description":"Shadowsocks URI Generator is a management and distribution platform for censorship circumvention services.","archived":false,"fork":false,"pushed_at":"2025-03-24T22:10:46.000Z","size":1202,"stargazers_count":24,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T08:11:17.272Z","etag":null,"topics":["automation","c-sharp","cli","deployment","oocv1","open-online-config","outline-server","shadowsocks","sip002","sip003","sip008","uri-generation"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/database64128.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-21T07:05:17.000Z","updated_at":"2025-03-24T22:10:49.000Z","dependencies_parsed_at":"2023-02-18T15:15:32.169Z","dependency_job_id":"1c509e26-dad4-413b-bed1-1915b2e939da","html_url":"https://github.com/database64128/shadowsocks-uri-generator","commit_stats":{"total_commits":445,"total_committers":4,"mean_commits":111.25,"dds":0.4089887640449438,"last_synced_commit":"de507ff3225fe0dbe890e60446fd0a3498ec13dc"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/database64128%2Fshadowsocks-uri-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/database64128%2Fshadowsocks-uri-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/database64128%2Fshadowsocks-uri-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/database64128%2Fshadowsocks-uri-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/database64128","download_url":"https://codeload.github.com/database64128/shadowsocks-uri-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246385451,"owners_count":20768668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","c-sharp","cli","deployment","oocv1","open-online-config","outline-server","shadowsocks","sip002","sip003","sip008","uri-generation"],"created_at":"2024-10-03T13:13:59.101Z","updated_at":"2025-10-03T15:45:45.187Z","avatar_url":"https://github.com/database64128.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌐 Shadowsocks URI Generator\n\n[![Build](https://github.com/database64128/shadowsocks-uri-generator/actions/workflows/build.yml/badge.svg)](https://github.com/database64128/shadowsocks-uri-generator/actions/workflows/build.yml)\n[![Release](https://github.com/database64128/shadowsocks-uri-generator/actions/workflows/release.yml/badge.svg)](https://github.com/database64128/shadowsocks-uri-generator/actions/workflows/release.yml)\n[![Nuget](https://img.shields.io/nuget/v/ShadowsocksUriGenerator)](https://www.nuget.org/packages/ShadowsocksUriGenerator/)\n[![AUR version](https://img.shields.io/aur/version/ss-uri-gen-git?label=ss-uri-gen-git)](https://aur.archlinux.org/packages/ss-uri-gen-git/)\n[![AUR version](https://img.shields.io/aur/version/ss-uri-gen-server-git?label=ss-uri-gen-server-git)](https://aur.archlinux.org/packages/ss-uri-gen-server-git/)\n[![AUR version](https://img.shields.io/aur/version/ss-uri-gen-chatbot-telegram-git?label=ss-uri-gen-chatbot-telegram-git)](https://aur.archlinux.org/packages/ss-uri-gen-chatbot-telegram-git/)\n[![AUR version](https://img.shields.io/aur/version/ss-uri-gen-rescue-git?label=ss-uri-gen-rescue-git)](https://aur.archlinux.org/packages/ss-uri-gen-rescue-git/)\n\nShadowsocks URI Generator is a management and distribution platform for censorship circumvention services.\n\n## Features\n\n- Manage users, nodes, and groups with intuitive commands.\n- API Server for management and online config.\n- Deploy and manage [Outline servers](https://github.com/Jigsaw-Code/outline-server).\n- Retrieve user credentials automatically from Outline servers, or add credentials manually in plaintext or `base64url`.\n- Gather data usage statistics from Outline servers.\n- Generate data usage report and export as CSV.\n- Manage data usage limit on users and groups. Enforce data limit on Outline servers.\n- Generate [SIP002](https://shadowsocks.org/en/spec/SIP002-URI-Scheme.html) `ss://` URLs for users.\n- Support for [SIP003](https://shadowsocks.org/en/spec/Plugin.html) plugins.\n- Online config delivery with support for [Open Online Config](https://github.com/Shadowsocks-NET/OpenOnlineConfig), [SIP008](https://shadowsocks.org/en/wiki/SIP008-Online-Configuration-Delivery.html), and V2Ray outbound files.\n- Run as a service to execute scheduled tasks.\n- Easy user interactions via [Telegram bots](https://core.telegram.org/bots).\n\n## Build\n\nPrerequisites: .NET 9 SDK\n\n```console\n$ # Build with Release configuration\n$ dotnet build -c Release\n\n$ # Publish as framework-dependent\n$ dotnet publish ShadowsocksUriGenerator -c Release\n\n$ # Publish as self-contained for Linux x64\n$ dotnet publish ShadowsocksUriGenerator -c Release \\\n    -p:PublishSingleFile=true \\\n    -p:PublishTrimmed=true \\\n    -p:DebuggerSupport=false \\\n    -p:EnableUnsafeBinaryFormatterSerialization=false \\\n    -p:EnableUnsafeUTF7Encoding=false \\\n    -p:InvariantGlobalization=true \\\n    -r linux-x64 --self-contained\n```\n\n## API Server\n\nThe API Server provides an API endpoint for basic management tasks and online config.\n\nTo start the server, simple run the binary or start the systemd service:\n\n```console\n$ ss-uri-gen-server\n```\n\n```console\n$ systemctl --user enable --now ss-uri-gen-server.service\n```\n\nSome `appsettings.json` samples are included in the project directory. `appsettings.systemd.json` is configured to use the systemd logging format.\n\nTo generate API URLs and tokens, make sure to set `ApiServerBaseUrl` and `ApiServerSecretPath`:\n\n```console\n$ # Set ApiServerBaseUrl and ApiServerSecretPath.\n$ ss-uri-gen settings set --api-server-base-url https://example.com --api-server-secret-path 8c1da4d8-8684-4a2c-9abb-57b9d5fa7e52\n$ # Get API URLs and tokens from CLI.\n$ ss-uri-gen online-config get-links\n```\n\nLinked Telegram users can get their API URLs and tokens from the Telegram bot by executing `/get_online_config_links`.\n\n## CLI\n\nThe CLI is the primary management tool for Shadowsocks URI Generator.\n\n```console\n$ # See usage guide.\n$ ss-uri-gen --help\n\n$ # Enter interactive mode (REPL).\n$ ss-uri-gen interactive\n\n$ # Run as a service to execute scheduled tasks.\n$ ss-uri-gen service --interval 3600 --pull-outline-server --generate-online-config\n\n$ # Add users.\n$ ss-uri-gen user add MyUserA MyUserB\n\n$ # Add groups.\n$ ss-uri-gen group add MyGroupA MyGroupB\n\n$ # Add a new node.\n$ ss-uri-gen node add MyGroupA MyNodeA 1.1.1.1 853\n\n$ # Add a new node with v2ray-plugin.\n$ ss-uri-gen node add MyGroupB MyNodeB 1.1.1.1 853 --plugin v2ray-plugin --plugin-opts \"tls;host=cloudflare-dns.com\"\n\n$ # Deactivate a node to exclude it from delivery.\n$ ss-uri-gen node deactivate MyGroupB MyNodeB\n\n$ # Join a group.\n$ ss-uri-gen user join MyUserB MyGroupB\n\n$ # Add multiple users to a group.\n$ ss-uri-gen group add-user MyGroupA MyUserA MyUserB\n\n$ # Add a credential associating MyGroupA with MyUserA.\n$ ss-uri-gen user add-credential MyUserA MyGroupA --method aes-256-gcm --password MyPassword\n\n$ # Add a credential in base64url.\n$ ss-uri-gen user add-credential MyUserB MyGroupA --userinfo-base64url eGNoYWNoYTIwLWlldGYtcG9seTEzMDU6TXlQYXNzd29yZA\n\n$ # Print a user's ss:// links.\n$ ss-uri-gen user get-ss-links MyUserA\n\n$ # Get a user's data usage metrics.\n$ ss-uri-gen user get-data-usage MyUserA\n\n$ # Get a group's data usage metrics.\n$ ss-uri-gen group get-data-usage MyGroupA\n\n$ # Generate Open Online Config (OOC) v1 files.\n$ ss-uri-gen online-config generate\n\n$ # Print all users' Open Online Config (OOC) v1 delivery URLs.\n$ ss-uri-gen online-config get-links\n\n$ # Associate a group with an Outline server.\n$ ss-uri-gen outline-server add MyGroupA '{\"apiUrl\":\"https://localhost/example\",\"certSha256\":\"EXAMPLE\"}'\n\n$ # Change Outline server settings.\n$ ss-uri-gen outline-server set MyGroupA --name MyOutlineA --hostname github.com --metrics true\n\n$ # Pull updates from Outline server.\n$ ss-uri-gen outline-server pull MyGroupA\n\n$ # Deploy local configuration to Outline server.\n$ ss-uri-gen outline-server deploy MyGroupA\n\n$ # Generate data usage report and export as CSV to current directory.\n$ ss-uri-gen report --csv-outdir .\n\n$ # Set default user for Outline server's access key id 0.\n$ ss-uri-gen settings set --outline-server-global-default-user MyUserA\n\n$ # Settings: change the online configuration generation output directory to 'sip008'.\n$ ss-uri-gen settings set --online-config-output-directory sip008\n\n$ # Rescue tool: rebuild database from generated online config.\n$ ss-uri-gen-rescue --online-config-dir /path/to/online/config\n```\n\n## Telegram Bot\n\nThe Telegram bot can act as a client portal for your service. The user ID is used as the secret key for authentication.\n\nSend your users their user ID, so they can use `/link \u003cuser_id\u003e` to link their Telegram account to their registered user.\n\nSee the full [command list](ShadowsocksUriGenerator.Chatbot.Telegram/UpdateHandler.cs) for what the bot can do. Some commands can be disabled in the config.\n\nTo host your Telegram bot, register a bot at [Bot Father](https://t.me/BotFather) and get the bot token. Then choose one of the following methods:\n\n```console\n$ # Method 1: Set the bot token in the config.\n$ ss-uri-gen-chatbot-telegram config set --bot-token \"1234567:4TT8bAc8GHUspu3ERYn-KGcvsvGB9u_n4ddy\"\n$ # Start the bot.\n$ ss-uri-gen-chatbot-telegram\n```\n\n```console\n$ # Method 2: Set the bot token as an environment variable.\n$ export TELEGRAM_BOT_TOKEN=\"1234567:4TT8bAc8GHUspu3ERYn-KGcvsvGB9u_n4ddy\"\n$ # Start the bot.\n$ ss-uri-gen-chatbot-telegram\n```\n\n```console\n$ # Method 3: Start the bot and pass the bot token as an argument.\n$ ss-uri-gen-chatbot-telegram --bot-token \"1234567:4TT8bAc8GHUspu3ERYn-KGcvsvGB9u_n4ddy\"\n```\n\n## License\n\n- This project is licensed under [GPLv3](LICENSE).\n- The icons are from [Material Design Icons](https://materialdesignicons.com/) and are licensed under the [Pictogrammers Free License](https://dev.materialdesignicons.com/license).\n- [`System.CommandLine`](https://github.com/dotnet/command-line-api) is licensed under the MIT license.\n- `System.Linq.Async`, `System.Interactive.Async` and `System.Reactive` are from [dotnet/reactive](https://github.com/dotnet/reactive). They are licensed under the MIT license.\n- [`Telegram.Bot`](https://github.com/TelegramBots/Telegram.Bot) and [`Telegram.Bot.Extensions.Polling`](https://github.com/TelegramBots/Telegram.Bot.Extensions.Polling) are licensed under the MIT license.\n\n© 2025 database64128\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabase64128%2Fshadowsocks-uri-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabase64128%2Fshadowsocks-uri-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabase64128%2Fshadowsocks-uri-generator/lists"}