{"id":13436225,"url":"https://github.com/hashicorp/serf","last_synced_at":"2025-09-09T20:12:20.882Z","repository":{"id":10948041,"uuid":"13257135","full_name":"hashicorp/serf","owner":"hashicorp","description":"Service orchestration and management tool.","archived":false,"fork":false,"pushed_at":"2025-03-12T04:38:26.000Z","size":7302,"stargazers_count":5935,"open_issues_count":133,"forks_count":598,"subscribers_count":458,"default_branch":"master","last_synced_at":"2025-05-04T11:55:12.184Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/hashicorp/serf/blob/master/docs/index.html.markdown","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hashicorp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-01T22:12:50.000Z","updated_at":"2025-04-29T10:56:01.000Z","dependencies_parsed_at":"2023-10-13T06:46:15.809Z","dependency_job_id":"d7d571b6-d51c-40dd-aa4d-400bf452001d","html_url":"https://github.com/hashicorp/serf","commit_stats":{"total_commits":1655,"total_committers":139,"mean_commits":"11.906474820143885","dds":0.6749244712990936,"last_synced_commit":"526dcd6b16a90f5a3baeec31bee618021d70cd94"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fserf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fserf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fserf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fserf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hashicorp","download_url":"https://codeload.github.com/hashicorp/serf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252330683,"owners_count":21730688,"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":[],"created_at":"2024-07-31T03:00:45.664Z","updated_at":"2025-05-04T11:55:17.820Z","avatar_url":"https://github.com/hashicorp.png","language":"Go","funding_links":[],"categories":["Go","开源类库","Networking, Distributed, Microservices \u0026 Cloud - Tools \u0026 Services","Open source library","Remote Container Manager / Orchestration","others","Workload Orchestration \u0026 Scheduling"],"sub_categories":["微服务","Microservices"],"readme":"# Serf [![Build Status](https://github.com/hashicorp/serf/workflows/Checks/badge.svg)](https://github.com/hashicorp/serf/actions) [![Join the chat at https://gitter.im/hashicorp-serf/Lobby](https://badges.gitter.im/hashicorp-serf/Lobby.svg)](https://gitter.im/hashicorp-serf/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n\n\u003e [!NOTE]\n\u003e Looking for serf.io? The Serf website was shut down on 10/02/2024. The docs\npreviously served from serf.io can be found\n[https://github.com/hashicorp/serf/blob/master/docs/index.html.markdown](https://github.com/hashicorp/serf/blob/master/docs/index.html.markdown)\n\n\n* Website: https://github.com/hashicorp/serf\n* Chat: [Gitter](https://gitter.im/hashicorp-serf/Lobby)\n* Mailing list: [Google Groups](https://groups.google.com/group/serfdom/)\n\nSerf is a decentralized solution for service discovery and orchestration\nthat is lightweight, highly available, and fault tolerant.\n\nSerf runs on Linux, Mac OS X, and Windows. An efficient and lightweight gossip\nprotocol is used to communicate with other nodes. Serf can detect node failures\nand notify the rest of the cluster. An event system is built on top of\nSerf, letting you use Serf's gossip protocol to propagate events such\nas deploys, configuration changes, etc. Serf is completely masterless\nwith no single point of failure.\n\nHere are some example use cases of Serf, though there are many others:\n\n* Discovering web servers and automatically adding them to a load balancer\n* Organizing many memcached or redis nodes into a cluster, perhaps with\n  something like [twemproxy](https://github.com/twitter/twemproxy) or\n  maybe just configuring an application with the address of all the\n  nodes\n* Triggering web deploys using the event system built on top of Serf\n* Propagating changes to configuration to relevant nodes.\n* Updating DNS records to reflect cluster changes as they occur.\n* Much, much more.\n\n## Quick Start\n\nFirst, [download a pre-built Serf binary](https://releases.hashicorp.com/serf)\nfor your operating system, [compile Serf yourself](#developing-serf), or install\nusing `go get -u github.com/hashicorp/serf/cmd/serf`.\n\nNext, let's start a couple Serf agents. Agents run until they're told to quit\nand handle the communication of maintenance tasks of Serf. In a real Serf\nsetup, each node in your system will run one or more Serf agents (it can\nrun multiple agents if you're running multiple cluster types. e.g. web\nservers vs. memcached servers).\n\nStart each Serf agent in a separate terminal session so that we can see\nthe output of each. Start the first agent:\n\n```\n$ serf agent -node=foo -bind=127.0.0.1:5000 -rpc-addr=127.0.0.1:7373\n...\n```\n\nStart the second agent in another terminal session (while the first is still\nrunning):\n\n```\n$ serf agent -node=bar -bind=127.0.0.1:5001 -rpc-addr=127.0.0.1:7374\n...\n```\n\nAt this point two Serf agents are running independently but are still\nunaware of each other. Let's now tell the first agent to join an existing\ncluster (the second agent). When starting a Serf agent, you must join an\nexisting cluster by specifying at least one existing member. After this,\nSerf gossips and the remainder of the cluster becomes aware of the join.\nRun the following commands in a third terminal session.\n\n```\n$ serf join 127.0.0.1:5001\n...\n```\n\nIf you're watching your terminals, you should see both Serf agents\nbecome aware of the join. You can prove it by running `serf members`\nto see the members of the Serf cluster:\n\n```\n$ serf members\nfoo    127.0.0.1:5000    alive\nbar    127.0.0.1:5001    alive\n...\n```\n\nAt this point, you can ctrl-C or force kill either Serf agent, and they'll\nupdate their membership lists appropriately. If you ctrl-C a Serf agent,\nit will gracefully leave by notifying the cluster of its intent to leave.\nIf you force kill an agent, it will eventually (usually within seconds)\nbe detected by another member of the cluster which will notify the\ncluster of the node failure.\n\n## Documentation\n\nFull, comprehensive documentation is viewable on the Serf website:\n\nhttps://github.com/hashicorp/serf/tree/master/docs\n\n## Developing Serf\n\nIf you wish to work on Serf itself, you'll first need [Go](https://golang.org)\ninstalled (version 1.10+ is _required_). Make sure you have Go properly\n[installed](https://golang.org/doc/install),\nincluding setting up your [GOPATH](https://golang.org/doc/code.html#GOPATH).\n\nNext, clone this repository into `$GOPATH/src/github.com/hashicorp/serf` and\nthen just type `make`. In a few moments, you'll have a working `serf` executable:\n\n```\n$ make\n...\n$ bin/serf\n...\n```\n\n*NOTE: `make` will also place a copy of the executable under `$GOPATH/bin/`*\n\nSerf is first and foremost a library with a command-line interface, `serf`. The\nSerf library is independent of the command line agent, `serf`.  The `serf`\nbinary is located under `cmd/serf` and can be installed stand alone by issuing\nthe command `go get -u github.com/hashicorp/serf/cmd/serf`.  Applications using\nthe Serf library should only need to include `github.com/hashicorp/serf`.\n\nTests can be run by typing `make test`.\n\nIf you make any changes to the code, run `make format` in order to automatically\nformat the code according to Go [standards](https://golang.org/doc/effective_go.html#formatting).\n\n\n ## Metrics Emission and Compatibility\n\n This library can emit metrics using either `github.com/armon/go-metrics` or `github.com/hashicorp/go-metrics`. Choosing between the libraries is controlled via build tags. \n\n **Build Tags**\n * `armonmetrics` - Using this tag will cause metrics to be routed to `armon/go-metrics`\n * `hashicorpmetrics` - Using this tag will cause all metrics to be routed to `hashicorp/go-metrics`\n\n If no build tag is specified, the default behavior is to use `armon/go-metrics`. \n\n **Deprecating `armon/go-metrics`**\n\n Emitting metrics to `armon/go-metrics` is officially deprecated. Usage of `armon/go-metrics` will remain the default until mid-2025 with opt-in support continuing to the end of 2025.\n\n **Migration**\n To migrate an application currently using the older `armon/go-metrics` to instead use `hashicorp/go-metrics` the following should be done.\n\n 1. Upgrade libraries using `armon/go-metrics` to consume `hashicorp/go-metrics/compat` instead. This should involve only changing import statements. All repositories in the `hashicorp` namespace\n 2. Update an applications library dependencies to those that have the compatibility layer configured.\n 3. Update the application to use `hashicorp/go-metrics` for configuring metrics export instead of `armon/go-metrics`\n    * Replace all application imports of `github.com/armon/go-metrics` with `github.com/hashicorp/go-metrics`\n    * Instrument your build system to build with the `hashicorpmetrics` tag.\n\n Eventually once the default behavior changes to use `hashicorp/go-metrics` by default (mid-2025), you can drop the `hashicorpmetrics` build tag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fserf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhashicorp%2Fserf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fserf/lists"}